Configurar clusters membros da frota para autenticação OIDC

Este documento descreve como administradores de cluster ou operadores de aplicativos podem configurar clusters para oferecer suporte à autenticação usando um provedor OpenID Connect (OIDC) de terceiros.

Limitações

Use um tipo de cluster compatível com OIDC.

Antes de começar

1. Install the Google Cloud CLI.

2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

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

   gcloud init

4. Depois que a gcloud CLI é inicializada, ela precisa ser atualizada e os componentes necessários instalados:

   gcloud components update
   gcloud components install kubectl

5. Verifique se o administrador da plataforma forneceu todas as informações necessárias do provedor. Para mais informações, consulte Compartilhar os detalhes do provedor de identidade.
6. Para autenticar usando o console Google Cloud , registre cada cluster que você quer configurar na frota do projeto. Para mais informações, consulte Visão geral da criação de frotas.
7. Para se conectar a um plano de controle de cluster da AWS ou do Azure que esteja fora da rede VPC atual por meio de um Bastion Host, verifique se você criou o Bastion Host e iniciou um túnel SSH na porta 8118. Ao executar comandos kubectl neste documento, adicione o prefixo HTTPS_PROXY=http://localhost:PORT, em que PORT é o número da porta que você usou ao iniciar o túnel SSH.
8. Para clusters do GKE no Google Cloud, registre os clusters na sua frota.

Configurar clusters

Para configurar a autenticação em um cluster usando o OIDC, adicione as seguintes informações a um recurso personalizado do Kubernetes chamado ClientConfig:

• Informações sobre seu provedor de identidade, como um ID e uma chave secreta do cliente.
• Informações sobre os JSON Web Tokens (JWTs) que seu provedor de identidade usa para autenticação.
• Outros escopos ou parâmetros exclusivos do seu provedor de identidade.

Para mais informações sobre as informações que você precisa do administrador da plataforma ou de quem gerencia a identidade na sua organização, consulte Compartilhar os detalhes do provedor de identidade.

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

Para editar o ClientConfig do default, conecte-se ao cluster kubectl e execute o seguinte comando:

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

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

Um editor de texto carrega o recurso ClientConfig do cluster. Adicione o objeto spec.authentication.oidc conforme mostrado no exemplo a seguir. Não modifique nenhum dado padrão que já tenha sido gravado.

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 provedor de identidade, sub identifica o usuário e groupList lista os grupos de segurança a que o usuário 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

É possível adicionar várias configurações de provedores de identidade OIDC, LDAP e SAML ao mesmo ClientConfig. O cluster tenta se autenticar com cada configuração na ordem em que elas são definidas e para após a primeira autenticação bem-sucedida. O exemplo a seguir de ClientConfig define vários provedores de identidade em uma 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 do ClientConfig

A tabela a seguir descreve os campos do objeto oidc do ClientConfig. Os campos que você precisa adicionar dependem dos tokens do provedor de identidade e de como o administrador da plataforma configurou o provedor.

Campo	Obrigatório	Descrição	Formato
name	sim	O nome que você quer usar para identificar essa configuração, normalmente o nome do provedor de identidade. O nome de configuração precisa começar com uma letra seguida por até 39 letras minúsculas, números ou hifens, mas não pode terminar com um hífen.	String
certificateAuthorityData	Não	Se fornecida pelo administrador da plataforma, uma string de certificado codificada em PEM para o provedor de identidade. Inclua a string resultante em certificateAuthorityData como uma única linha.	String
clientID	Sim	O ID do cliente do provedor de identidade.	String
clientSecret	Não	Senha secreta entre o aplicativo cliente OIDC e o provedor OIDC.	String
deployCloudConsoleProxy	Não	Especifica se um proxy é implantado que permite que o Google Cloud console se conecte a um provedor de identidade local que não seja acessível publicamente pela Internet. Por padrão, essa opção é definida como false.	Booleano
parâmetros extras	Não	Parâmetros de chave=valor adicionais a serem enviados ao provedor 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 declaração do JWT (nome do campo) que seu provedor usa para retornar os grupos de segurança de uma conta.	String
groupPrefix	Não	O prefixo que você quer adicionar aos nomes dos grupos de segurança para evitar conflitos com nomes existentes nas suas regras de controle de acesso se você tiver configurações para vários provedores de identidade (normalmente o nome do provedor).	String
issuerURI	Sim	O URI em que as solicitações de autorização são feitas para seu provedor de identidade. O URI precisa usar HTTPS e não pode terminar com uma barra final.	String do URL
kubectlRedirectURI	Sim	O URL de redirecionamento e a porta usados pela gcloud CLI e especificados pelo administrador da plataforma no registro, geralmente no formato http://localhost:PORT/callback.	String do URL
escopos	Sim	Outros escopos a serem enviados ao provedor OpenID. Por exemplo, o Microsoft Azure e o Okta exigem o escopo offline_access.	Lista delimitada por vírgulas
userClaim	Não	A declaração do JWT (nome do campo) que o provedor usa para identificar uma conta de usuário. Se você não especificar um valor aqui, o padrão será "sub", que é a declaração do User ID usada por muitos provedores. Você pode escolher outras declarações, como "e-mail" ou "nome", dependendo do provedor OpenID. Declarações que não sejam "email" são prefixadas com o URL do emissor para evitar conflitos de nomenclatura.	String
userPrefix	Não	Se você não quiser usar o prefixo padrão, o prefixo que você quer adicionar ao nome do usuário evita conflitos com nomes existentes.	String
enableAccessToken	Não	Se ativado, o cluster poderá usar o endpoint userinfo do provedor de identidade para receber informações de grupos quando um usuário fizer login na linha de comando. Isso permite que você use grupos de segurança para autorização se tiver um provedor (como o Okta) que forneça declarações de grupo a partir desse endpoint. Se não for definido, será considerado false.	Booleano
proxy	Não	Endereço do servidor proxy a ser usado para se conectar ao provedor de identidade, se aplicável. Talvez seja necessário defini-lo se, por exemplo, o cluster estiver em uma rede particular e precisar se conectar a um provedor de identidade público. Por exemplo, http://user:password@10.10.10.10:8888.	String

Depois de editar o ClientConfig, salve o arquivo para atualizar o ClientConfig do cluster. Se você cometer algum erro de sintaxe, vai receber uma solicitação para corrigir esses erros e salvar o arquivo.

Configurações específicas do provedor

Esta seção fornece orientações sobre a configuração de alguns provedores OIDC conhecidos, incluindo exemplos de configurações que você pode copiar e editar com seus próprios detalhes.

Atenção: use o OIDC padrão ou o método do Microsoft Entra ID (avançado). Não aplique os dois. Essas configurações são mutuamente exclusivas. A tentativa de usar os dois simultaneamente faz com que o plug-in OIDC padrão substitua o plug-in do Microsoft Entra ID (avançado), o que leva a falhas de autenticação para usuários com mais de 200 associações a grupos.

Microsoft Entra ID

Essa é a configuração padrão para configurar um cluster para autenticação com o Microsoft Entra ID. O uso dessa configuração permite que o cluster receba informações de associação de usuários e grupos do Microsoft Entra ID, além de permitir configurar o controle de acesso baseado em função (RBAC) do Kubernetes com base em grupos. No entanto, o uso dessa configuração limita a recuperação de aproximadamente 200 grupos por usuário.

Se você precisar recuperar mais de 200 grupos por usuário, 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:

• CLIENT_ID: o ID do cliente do Microsoft Entra ID.
• CLIENT_SECRET: senha secreta entre o aplicativo cliente OIDC e o provedor OIDC.
• TENANT_ID: o tipo de conta do Microsoft Entra ID a ser autenticada. Os valores aceitos são o ID ou o nome do locatário das contas que pertencem a um locatário específico. O nome do locatário também é conhecido como domínio principal. Para detalhes sobre como encontrar esses valores, consulte Encontrar o ID do locatário e o nome de domínio principal do Microsoft Entra.
• PORT: o número da porta escolhida para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registro.

Microsoft Entra ID (avançado)

Essa configuração opcional para o Microsoft Entra ID permite que o cluster recupere informações de usuários e grupos sem limite no número de grupos por usuário usando a API Microsoft Graph.

Para saber mais sobre as plataformas compatíveis com essa configuração, consulte Configuração avançada para o Microsoft Entra ID.

Se você precisar recuperar menos de 200 grupos por usuário, recomendamos que use a configuração padrão com uma âncora oidc no ClientConfig. Para mais informações, consulte as instruções do Microsoft Entra ID.

Todos os campos do exemplo a seguir 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:

• NAME: o nome que você quer usar para identificar essa configuração, normalmente o nome do provedor de identidade. O nome de configuração precisa começar com uma letra seguida por até 39 letras minúsculas, números ou hifens, mas não pode terminar com um hífen.
• PROXY_URL: Endereço do servidor proxy a ser usado para se conectar ao provedor de identidade, se aplicável. Talvez seja necessário defini-lo se, por exemplo, o cluster estiver em uma rede particular e precisar se conectar a um provedor de identidade público. Por exemplo, http://user:password@10.10.10.10:8888.
• CLIENT_ID: o ID do cliente do Microsoft Entra ID.
• CLIENT_SECRET: senha secreta entre o aplicativo cliente OIDC e o provedor OIDC.
• TENANT: o tipo de conta do Microsoft Entra a ser autenticada. Os valores aceitos são o ID ou o nome do locatário das contas que pertencem a um locatário específico. O nome do locatário também é conhecido como domínio principal. Para detalhes sobre como encontrar esses valores, consulte Encontrar o ID do locatário e o nome de domínio principal do Microsoft Entra.
• PORT: o número da porta escolhida para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registro.
• GROUP_FORMAT: o formato em que você quer recuperar as informações do grupo. Esse campo pode ter valores correspondentes a ID ou NAME dos grupos de usuários. Essa configuração está disponível apenas para clusters em implantações bare metal do Google Distributed Cloud.
• USER_CLAIM (opcional): a declaração do JWT (nome do campo) que o provedor usa para identificar uma conta. Se você não especificar um valor aqui, o cluster usará um valor na ordem "email", "preferred_username" ou "sub" para buscar os detalhes do usuário. Esse atributo pode ser usado na versão 1.28.

Okta

Veja a seguir como configurar a autenticação usando usuários e grupos com o Okta como seu provedor de identidade. Essa configuração permite que o cluster recupere declarações de usuários e grupos usando um token de acesso e o endpoint userinfo do Okta.

Observação: embora essa configuração seja para o Okta, você também pode recuperar informações de usuários e grupos de qualquer outro provedor de identidade compatível com um endpoint userinfo. Na configuração, especifique enableAccessToken: true para usar esse recurso.

# 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 grupos

Para usuários do Okta, o cluster pode recuperar informações de grupo de usuários cujos nomes de grupo, se concatenados, têm um tamanho inferior a 170.000 caracteres. Isso corresponde a uma associação de aproximadamente 650 grupos, dada a duração máxima do grupo do Okta. Se o usuário for um membro de muitos grupos, a chamada de autenticação falhará.

A seguir

Depois que a configuração for aplicada, defina o acesso do usuário a clusters.