Configurar o Provedor OIDC

OpenID Connect (OIDC) é um protocolo de autenticação baseado no OAuth 2.0. Ele permite configurar a autenticação de usuários em um cluster Kubernetes usando serviços como Google, Keycloak, Dex, GitHub e outros.

Configurar o provedor OIDC

Você pode configurar o provedor OIDC ao criar um cluster na Etapa 5. Provedor OIDC:

Ou posteriormente pela aba Gestão (Kubernetes → clique no cluster → Gestão):

Durante a configuração, informe os seguintes valores:

• Nome da conexão (obrigatório): nome exibido apenas no painel de controle. Não afeta o funcionamento do OIDC.
• URL do emissor (obrigatório): endereço do provedor OIDC. Por exemplo:
  • https://<domain>/realms/<realm> for Keycloak
  • https://accounts.google.com for Google
• Client ID (obrigatório): identificador do cliente registrado no provedor OIDC.
• Username claim: campo do token ID que o Kubernetes usará como nome de usuário (por exemplo, sub, preferred_username ou email).
• Groups claim: campo do token ID que contém a lista de grupos do usuário. Usado para controle de acesso RBAC baseado em grupos.

Após inserir os parâmetros necessários, clique em Salvar.

Instalar o kubelogin

O utilitário kubelogin é usado para obter um token de ID do provedor e passá-lo ao Kubernetes ao executar comandos via kubectl.

Linux

Baixe o arquivo com a versão mais recente:

curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip

Extraia o arquivo:

unzip kubelogin_linux_amd64.zip

Torne o binário executável:

chmod +x kubelogin

Mova-o para um diretório do sistema:

sudo mv kubelogin /usr/local/bin/

macOS

Instale com Homebrew:

brew install kubelogin

Windows

Instale com Chocolatey:

choco install kubelogin

Krew

Se você usa o gerenciador de plugins Krew:

kubectl krew install oidc-login

Obter um token

Execute o comando:

kubelogin get-token \
  --oidc-issuer-url=https://oidc-provider-address \
  --oidc-client-id=client_id \
  --oidc-client-secret=secret

Uma janela do navegador será aberta solicitando login. Após a autenticação, um token em formato JSON será exibido. Por exemplo:

{"kind":"ExecCredential","apiVersion":"client.authentication.k8s.io/v1beta1","spec":{"interactive":false},"status":{"expirationTimestamp":"2025-04-24T08:48:30Z","token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ3X3AxNzlsdkkzTnltWW01M09GZEpWeDJGeGJ6cGxoX2s5OHVFcmtjRmY4In0.eyJleHAiOjE3NDU0ODQ1MTAsImlhdCI6MTc0NTQ4NDQ1MSwiYXV0aF90aW1lIjoxNzQ1NDg0NDUwLCJqdGkiOiJkNTVmYjkzMy0zY2NlLTRkODYtYTcxZS1lNzc1ODZkN2E2ZGIiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLm5kb2xnaWtoLnNpdGUvcmVhbG1zL21hc3RlciIsImF1ZCI6InRlc3QiLCJzdWIiOiIyY2U5NDk5Ni0zN2NlLTQ1NDEtOGFiOS00ZTk0MWE2YjhmYW123eXAiOiJJRCIsImF6cCI6InRlc3QiLCJub25jZSI6InhuWGNLMTlIVUprRTB0N3BXbVJ6NXJBWC0ya0h4NFpVaGdhbEJ2OW1QsfaiLCJzZXNzaW9uX3N0YXRlIjoiYjZmOWRmNmMtMjNhMS00OGU4LTkwMDQtOWJlYmFmNzY0OGU4IiwiYXRfaGFzaCI6IldocDAtQkdCTmhWNTUwc082eW9wS2ciLCJhY3IiOiIxIiwic2lkIjoiYjZmOWRmNmMtMjNhMS00OGU4LTkwMDQtOWJlYmFmNzY0OGU4IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJuYW1lIjoidGVzdCB0ZXN0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoidGVzdEBtYWlsLnJ1IiwiZ2l2ZW5fbmFtZSI6InRlc3QiLCJmYW1pbHlfbmFtZSI6InRlc3QiLCJlbWFpbCI6InRlc3RAbWFpbC5ydSJ9.GQjRT_gTjsdfuVwhPYCW5DlqL_pbXpiYItIxNvOs9G8jUldV-3LyntQa4Zf4OSwzKldiJ4wZDRa-8pGI-BwD3SO1RxhkbYm_yTFxXDguxNdjstrFcCfLaslhBPqelpKC7DbsIqSLRIoixihPynIEMhEZRxvlDwZuYmWwyn7zMztQyGHPam_ujICIddcODBDBHA2Ksw_ZNwMAoU0sdMlI3fjTJst_Mh3jgzQRpFctc7X75JCL37HcZ6HBb6_9SWfmKHGO3ivFGs1pKtX6XDay8zt65DaEKM41iTjCzr-nKQ1Qk16fRypgsUauSJp_UHiGMiAUHSz66hQdvUr1uByg"}}

Para decodificar e visualizar o conteúdo do token:

echo "token" | cut -d '.' -f2 | base64 -d | jq

Exemplo de saída:

 {
  "exp": 1745480015,
  "iat": 1745479955,
  "auth_time": 1745479955,
  "jti": "4d9d243a-f62d-4150-94eb-5c535d2c0ea8",
  "iss": "https://keycloak.hostman.com/realms/master",
  "aud": "test-user",
  "sub": "2ce94996-37ce-4541-8ab9-4e941a6b8faa",
  "typ": "ID",
  "azp": "test-user",
  "nonce": "ubNzQ6KRI746Ab1WPGG3Z5tONUPDPx-sSud4aLKDlT4",
  "session_state": "e0933444-3a04-4e17-885c-1a7f93e0ebb3",
  "at_hash": "QpL9mrseqRikRIVEhdQrBQ",
  "acr": "1",
  "sid": "e0933444-3a04-4e17-885c-1a7f93e0ebb3",
  "email_verified": false,
  "name": "Hostman",
  "preferred_username": "test@example.com",
  "given_name": "test",
  "family_name": "test",
  "email": "test@example.com"
}

O nome do claim configurado como Username claim aparecerá aqui (o padrão é sub).

Configurar o RBAC

RBAC (Role-Based Access Control) é o mecanismo do Kubernetes para gerenciar permissões de usuários. Ele define quais recursos um usuário pode visualizar ou modificar. Consulte a documentação oficial para mais detalhes.

Para configurar o RBAC, crie um arquivo chamado oidc-access.yaml com o seguinte conteúdo:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: keycloak-cluster-role
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: keycloak-cluster-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: keycloak-cluster-role
subjects:
  - kind: User
    name: "https://oidc-provider#sub"
    apiGroup: rbac.authorization.k8s.io

Especifique o valor do campo sub do token no parâmetro name. Isso concederá acesso total (cluster-admin) ao usuário autenticado via OIDC.

Aplique o manifesto:

kubectl apply -f oidc-access.yaml

Para conceder acesso somente leitura (por exemplo, aos pods no namespace default), aplique o seguinte manifesto:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: readonly-pods
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: readonly-pods-binding
  namespace: default
roleRef:
  kind: Role
  name: readonly-pods
  apiGroup: rbac.authorization.k8s.io
subjects:
  - kind: User
    name: "https://oidc-provider#sub"
    apiGroup: rbac.authorization.k8s.io

Se você definiu um Username claim como preferred_username no painel, o Kubernetes usará esse valor como nome de usuário. Nesse caso, você pode usar um nome mais legível:

subjects:
  - kind: User
    name: "test@example.com"
    apiGroup: rbac.authorization.k8s.io

Configurar o kubectl para usar OIDC

Adicione o usuário OIDC ao seu kubeconfig:

kubectl config set-credentials oidc \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-interactive-mode=IfAvailable \
  --exec-command=kubelogin \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://oidc-provider-address \
  --exec-arg=--oidc-client-id=client_id \
  --exec-arg=--oidc-client-secret=secret

Defina o contexto atual para usar esse usuário:

kubectl config set-context --current --user=oidc

Verifique:

kubectl get pods

O navegador solicitará login. Após a autenticação, o comando deverá funcionar sem erros. Se o acesso for negado, verifique as regras de RBAC.

Se tudo estiver funcionando corretamente, você pode usar apenas OIDC e desativar a autenticação baseada em certificados. Para isso, comente ou remova as credenciais de certificado do kubeconfig:

# - name: xg60398-1032513
#   user:
# client-certificate-data: LS0tLS1CRUdJTiBD…
# client-key-data: LS0tLS1CRUdJ…

Desativar o provedor OIDC

Para desativar o provedor OIDC:

1. Acesse a seção Kubernetes.
2. Clique no cluster e abra a aba Gestão.
3. Clique em Editar ao lado do Provedor OIDC.
4. Clique em Excluir.

Após a remoção, todos os usuários autenticados via OIDC perderão o acesso. As regras de RBAC permanecerão e deverão ser removidas manualmente.

Para localizar role bindings vinculados:

kubectl get rolebindings --all-namespaces -o yaml | grep -B5 https://oidc-provider-address

Para excluí-los:

kubectl delete clusterrolebinding <name>

Para restaurar o acesso, se o kubeconfig estiver configurado para OIDC, volte para a autenticação baseada em certificados ou baixe o kubeconfig novamente no painel de controle.