Configure clusters de membros da frota para a autenticação OIDC

Este documento descreve como os administradores de clusters ou os operadores de aplicações podem configurar clusters para suportar a autenticação através de um fornecedor OpenID Connect (OIDC) de terceiros.

Limitações

Tem de usar um tipo de cluster que suporte OIDC.

Antes de começar

1. Install the Google Cloud CLI.

2. Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

3. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

4. Depois de inicializar a CLI gcloud, atualize-a e instale os componentes necessários:

   gcloud components update
   gcloud components install kubectl

5. Certifique-se de que o administrador da plataforma lhe deu todas as informações de fornecedor de que precisa. Para mais informações, consulte o artigo Partilhe os detalhes do fornecedor de identidade.
6. Para fazer a autenticação através da Google Cloud consola, registe cada cluster que quer configurar na sua frota de projetos. Para mais informações, consulte o artigo Vista geral da criação de frotas.
7. Para se ligar ao plano de controlo de um cluster da AWS ou do Azure que esteja fora da sua rede VPC atual através de um anfitrião de bastion, certifique-se de que criou o anfitrião de bastion e iniciou um túnel SSH na porta 8118. Quando executar comandos kubectl neste documento, adicione HTTPS_PROXY=http://localhost:PORT antes dos comandos, onde PORT é o número da porta que usou quando iniciou o túnel SSH.
8. Para clusters do GKE no Google Cloud, registe os clusters na sua frota.

Configure clusters

Para configurar a autenticação num cluster através do OIDC, adicione as seguintes informações a um recurso personalizado do Kubernetes denominado ClientConfig:

• Informações sobre o seu fornecedor de identidade, como um ID de cliente e um segredo.
• Informações sobre os tokens da Web JSON (JWTs) que o seu fornecedor de identidade usa para autenticação.
• Quaisquer âmbitos ou parâmetros adicionais que sejam exclusivos do seu fornecedor de identidade.

Para mais informações sobre as informações de que precisa do administrador da plataforma ou de quem gere a identidade na sua organização, consulte o artigo Partilhe os detalhes do fornecedor de identidade.

O cluster usa os campos no recurso personalizado ClientConfig para interagir com o seu fornecedor de identidade. Cada cluster tem um ClientConfig denominado default no namespace kube-public. Os campos específicos que modifica dependem do seu Fornecedor de identidade.

Para editar o default ClientConfig, certifique-se de que consegue estabelecer ligação ao cluster kubectl e, em seguida, execute o seguinte comando:

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Substitua KUBECONFIG_PATH pelo caminho para o ficheiro kubeconfig do seu cluster, por exemplo, $HOME/.kube/config.

Um editor de texto carrega o recurso ClientConfig do seu cluster. Adicione o objeto spec.authentication.oidc, conforme mostrado no exemplo seguinte. Não modifique nenhum dado predefinido que já tenha sido escrito.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL
# Rest of the resource is managed by Google. DO NOT MODIFY.

Por exemplo, considere os seguintes campos de token de identidade:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['[e-mail]', '[e-mail]']
  # Multiple lines are omitted here
}

Neste exemplo, iss é o URI do fornecedor de identidade, sub identifica o utilizador e groupList indica os grupos de segurança aos quais o utilizador pertence. Este exemplo mostra apenas uma amostra dos campos que o token real pode ter.

Para o token de exemplo anterior, atualize os seguintes campos no objeto spec.authentication.oidc do ClientConfig:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

Pode adicionar várias configurações de fornecedores de identidade OIDC, LDAP e SAML à mesma ClientConfig. O cluster tenta autenticar-se com cada configuração pela ordem em que são definidas e para após a primeira autenticação bem-sucedida. O exemplo ClientConfig seguinte define vários fornecedores de identidade numa ordem específica:

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

Campos OIDC de ClientConfig

A tabela seguinte descreve os campos do objeto ClientConfig oidc. Os campos que tem de adicionar dependem dos tokens do seu fornecedor de identidade e da forma como o administrador da plataforma configurou o fornecedor.

Campo	Obrigatória	Descrição	Formato
nome	sim	O nome que quer usar para identificar esta configuração, normalmente o nome do fornecedor de identidade. Um nome de configuração tem de começar por uma letra, seguida de até 39 letras minúsculas, números ou hífenes, e não pode terminar com um hífen.	String
certificateAuthorityData	Não	Se fornecido pelo administrador da plataforma, uma string de certificado com codificação PEM para o fornecedor de identidade. Inclua a string resultante em certificateAuthorityData como uma única linha.	String
clientID	Sim	O ID de cliente do Fornecedor de identidade.	String
clientSecret	Não	Segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.	String
deployCloudConsoleProxy	Não	Especifica se é implementado um proxy que permite que a Google Cloud consola se ligue a um fornecedor de identidade no local que não seja acessível publicamente através da Internet. Por predefinição, esta opção está definida como false.	Booleano
extraParams	Não	Parâmetros adicionais de chave=valor a enviar para o fornecedor de identidade, especificados como uma lista separada por vírgulas, por exemplo, `prompt=consent,access_type=offline`.	Lista delimitada por vírgulas
groupsClaim	Não	A reivindicação JWT (nome do campo) que o seu fornecedor usa para devolver os grupos de segurança de uma conta.	String
groupPrefix	Não	O prefixo que quer antepor aos nomes dos grupos de segurança para evitar conflitos com os nomes existentes nas suas regras de controlo de acesso se tiver configurações para vários fornecedores de identidade (normalmente, o nome do fornecedor).	String
issuerURI	Sim	O URI onde os pedidos de autorização são feitos ao seu fornecedor de identidade. O URI tem de usar HTTPS e não deve terminar com uma barra invertida.	String de URL
kubectlRedirectURI	Sim	O URL de redirecionamento e a porta usados pela CLI gcloud e especificados pelo administrador da plataforma no registo, normalmente no formato http://localhost:PORT/callback.	String de URL
âmbitos	Sim	Âmbitos adicionais a enviar para o fornecedor OpenID. Por exemplo, o Microsoft Azure e o Okta requerem o âmbito offline_access.	Lista delimitada por vírgulas
userClaim	Não	A reivindicação JWT (nome do campo) que o seu fornecedor usa para identificar uma conta de utilizador. Se não especificar um valor aqui, o valor predefinido é "sub", que é a reivindicação de ID do utilizador usada por muitos fornecedores. Pode escolher outras reivindicações, como "email" ou "nome", consoante o fornecedor OpenID. As reivindicações que não sejam "email" têm o prefixo do URL do emissor para evitar conflitos de nomenclatura.	String
userPrefix	Não	O prefixo que quer anteposto às reivindicações do utilizador para evitar conflitos com nomes existentes, se não quiser usar o prefixo predefinido.	String
enableAccessToken	Não	Se estiver ativado, o cluster pode usar o ponto final userinfo do fornecedor de identidade para obter informações de grupos quando um utilizador inicia sessão a partir da linha de comandos. Isto permite-lhe usar grupos de segurança para autorização se tiver um fornecedor (como o Okta) que forneça reivindicações de grupos a partir deste ponto final. Se não estiver definido, considera-se que é false.	Booleano
proxy	Não	Endereço do servidor proxy a usar para estabelecer ligação ao fornecedor de identidade, se aplicável. Pode ter de definir esta opção se, por exemplo, o seu cluster estiver numa rede privada e precisar de estabelecer ligação a um fornecedor de identidade público. Por exemplo: http://user:password@10.10.10.10:8888.	String

Depois de editar o ClientConfig, guarde o ficheiro para atualizar o ClientConfig do seu cluster. Se cometer erros de sintaxe, é apresentada uma mensagem para os corrigir e guardar o ficheiro.

Configurações específicas do fornecedor

Esta secção fornece orientações de configuração para alguns fornecedores de OIDC populares, incluindo configurações de exemplo que pode copiar e editar com os seus próprios detalhes.

Atenção: tem de usar o método OIDC padrão ou o Microsoft Entra ID (avançado). Não aplique ambas. Estas configurações são mutuamente exclusivas. A tentativa de usar ambos em simultâneo faz com que o plug-in OIDC padrão substitua o plug-in Microsoft Entra ID (avançado), o que leva a falhas de autenticação para utilizadores com mais de 200 associações a grupos.

Microsoft Entra ID

Esta é a configuração predefinida para configurar um cluster para autenticação com o Microsoft Entra ID. A utilização desta configuração permite que o cluster obtenha informações sobre a associação de utilizadores e grupos do Microsoft Entra ID e permite configurar o controlo de acesso baseado em funções (RBAC) do Kubernetes com base em grupos. No entanto, a utilização desta configuração limita a obtenção de aproximadamente 200 grupos por utilizador.

Se precisar de obter mais de 200 grupos por utilizador, consulte as instruções para o Microsoft Entra ID (avançado).

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

Substitua o seguinte:

• CLIENT_ID: o ID de cliente do Microsoft Entra ID.
• CLIENT_SECRET: segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.
• TENANT_ID: o tipo de conta do Microsoft Entra ID a autenticar. Os valores suportados são o ID do inquilino ou o nome do inquilino para contas pertencentes a um inquilino específico. O nome do inquilino também é conhecido como o domínio principal. Para ver detalhes sobre como encontrar estes valores, consulte o artigo Encontre o ID do inquilino e o nome do domínio principal do Microsoft Entra.
• PORT: o número da porta escolhido para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registo.

Microsoft Entra ID (avançado)

Esta configuração opcional para o Microsoft Entra ID permite ao cluster obter informações de utilizadores e grupos sem limite no número de grupos por utilizador, através da API Microsoft Graph.

Para ver informações sobre as plataformas que suportam esta configuração, consulte o artigo Configuração avançada para o Microsoft Entra ID.

Se precisar de obter menos de 200 grupos por utilizador, recomendamos que use a configuração predefinida com um elemento oidc no seu ClientConfig. Para mais informações, consulte as instruções para o Microsoft Entra ID.

Todos os campos na configuração do exemplo seguinte são obrigatórios.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM
# Multiple lines are omitted here. Do not modify any pre-filled data.

Substitua o seguinte:

• NAME: o nome que quer usar para identificar esta configuração, normalmente o nome do fornecedor de identidade. Um nome de configuração tem de começar por uma letra, seguida de até 39 letras minúsculas, números ou hífenes, e não pode terminar com um hífen.
• PROXY_URL: endereço do servidor proxy a usar para estabelecer ligação ao fornecedor de identidade, se aplicável. Pode ter de definir esta opção se, por exemplo, o seu cluster estiver numa rede privada e precisar de estabelecer ligação a um fornecedor de identidade público. Por exemplo: http://user:password@10.10.10.10:8888.
• CLIENT_ID: o ID de cliente do Microsoft Entra ID.
• CLIENT_SECRET: segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.
• TENANT: o tipo de conta do Microsoft Entra a autenticar. Os valores suportados são o ID do inquilino ou o nome do inquilino para contas pertencentes a um inquilino específico. O nome do inquilino também é conhecido como o domínio principal. Para ver detalhes sobre como encontrar estes valores, consulte o artigo Encontre o ID do inquilino e o nome do domínio principal do Microsoft Entra.
• PORT: o número da porta escolhido para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registo.
• GROUP_FORMAT: o formato no qual quer obter informações do grupo. Este campo pode assumir valores correspondentes a ID ou NAME dos grupos de utilizadores. Tenha em atenção que esta definição só está disponível para clusters em implementações do Google Distributed Cloud bare metal.
• USER_CLAIM (Opcional): a reivindicação JWT (nome do campo) que o seu fornecedor usa para identificar uma conta. Se não especificar um valor aqui, o cluster usa um valor na ordem de "email", "preferred_username" ou "sub" para obter os detalhes do utilizador. Este atributo pode ser usado a partir da versão 1.28.

Okta

A imagem seguinte mostra como configurar a autenticação usando utilizadores e grupos com o Okta como fornecedor de identidade. Esta configuração permite que o cluster obtenha reivindicações de utilizadores e grupos através de um token de acesso e do ponto final userinfo do Okta.

Nota: embora esta configuração seja para o Okta, também pode obter informações de utilizadores e grupos de qualquer outro fornecedor de identidade que suporte um ponto final userinfo. Na sua configuração, especifique enableAccessToken: true para usar esta funcionalidade.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

Limites de acesso de grupo

Para utilizadores do Okta, o cluster pode obter informações de grupos para utilizadores cujos nomes de grupos, se concatenados, tenham um comprimento inferior a 170 000 carateres. Isto corresponde a uma associação de aproximadamente 650 grupos, tendo em conta o comprimento máximo do grupo do Okta. Se o utilizador for membro de demasiados grupos, a chamada de autenticação falha.

O que se segue?

Depois de aplicar a configuração, continue a configurar o acesso dos utilizadores aos clusters.