Configurar clusters para o GKE Identity Service com o OIDC

Este documento é destinado a administradores de cluster ou operadores de aplicativos que querem configurar o GKE Identity Service em clusters individuais, permitindo que desenvolvedores e outros usuários façam login nos clusters usando os detalhes de identidade de um OpenID Connect". (OIDC). O guia pressupõe que você leu a visão geral do GKE Identity Service.

Para saber como configurar o GKE Identity Service para um cluster com um provedor LDAP, consulte Como configurar o GKE Identity Service com LDAP.
Para saber como configurar o GKE Identity Service no nível da frota para tipos de cluster compatíveis com sua configuração de autenticação gerenciada pelo Google Cloud, consulte Como configurar o GKE Identity Service para uma frota.

As instruções neste documento presumem que o GKE Identity Service já tenha sido registrado com seu provedor de identidade como um aplicativo cliente.

Visão geral da configuração

A configuração do GKE Identity Service para um cluster individual envolve os seguintes usuários e etapas:

O administrador da plataforma registra o GKE Identity Service como um aplicativo cliente com o provedor de identidade de sua preferência e recebe um ID e uma chave secreta do cliente. Para fazer isso, siga as instruções em Como configurar provedores do GKE Identity Service.
O administrador do cluster configura os clusters para usar o serviço seguindo as instruções nesta página.
O administrador do cluster define o acesso do usuário e, opcionalmente, configura o controle de acesso baseado em papéis (RBAC, na sigla em inglês) do Kubernetes para usuários nos clusters. Para fazer isso, siga as instruções em Como configurar o acesso do usuário do GKE Identity Service.

Pré-requisitos

Seu cluster precisa ser um cluster do GKE no local (VMware ou bare metal), na AWS ou no Azure. A configuração OIDC por cluster não é compatível com clusters anexados ou do GKE.
Para autenticar por meio do Console do Cloud, cada cluster que você quer configurar para autenticação OIDC precisa ser registrado na frota do projeto.

Antes de começar

Verifique se o administrador da plataforma forneceu todas as informações necessárias em Registrar o serviço de identidade do GKE com seu provedor antes de iniciar a configuração, incluindo o ID e a chave secreta do cliente para o serviço de identidade do GKE
Verifique se você tem as seguintes ferramentas de linha de comando instaladas:
- A versão mais recente da Google Cloud CLI, que inclui gcloud, a ferramenta de linha de comando para interagir com o Google Cloud. Se você precisar instalar a Google Cloud CLI, consulte o guia de instalação.
- kubectl para executar comandos em clusters do Kubernetes. Se precisar instalar kubectl, siga estas instruções.
Se você estiver usando o Cloud Shell como ambiente shell para interagir com o Google Cloud, essas ferramentas estarão instaladas.
Verifique se você inicializou a CLI gcloud para uso com o projeto em que os clusters estão registrados.
Se você precisar se conectar a um plano de controle do cluster do GKE da AWS ou do Azure que esteja fora da VPC atual por meio de um Bastion Host, verifique se você criou o Bastion Host e iniciou um túnel SSH na porta 8118 antes dessa configuração. Em seguida, anexe os comandos kubectl ao seguir este guia com HTTPS_PROXY=http://localhost:8118. Se você usou uma porta diferente ao iniciar o túnel SSH, substitua 8118 pela porta selecionada.

Configurar clusters

Para configurar os clusters para usar o provedor escolhido, o GKE Identity Service precisa especificar detalhes sobre o provedor de identidade, as informações nos tokens JWT fornecidos para identificação do usuário e outras informações fornecidas ao registrar o GKE Identity Service como um aplicativo cliente.

Por exemplo, se seu provedor criar tokens de identidade com os seguintes campos (entre outros), em que 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:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

...a configuração terá os seguintes campos correspondentes:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

O administrador da plataforma ou quem gerencia a identidade na sua organização, deve fornecer a você a maior parte das informações necessárias para criar a configuração.

O GKE Identity Service usa um tipo de recurso personalizado (CRD, na sigla em inglês) do Kubernetes chamado ClientConfig para configuração de cluster, com campos para todas as informações de que o GKE Identity Service precisa para interagir com o provedor de identidade. Cada cluster do GKE tem um recurso ClientConfig chamado default no namespace kube-public que você atualiza com os detalhes da configuração, seguindo as instruções abaixo.

Veja alguns exemplos de configurações específicas para provedores conhecidos em Configurações específicas do provedor.

kubectl

Para editar o ClientConfig padrão, conecte-se ao cluster por meio do kubectl e execute o seguinte comando:

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

Substitua KUBECONFIG_PATH pelo caminho para o arquivo kuneconfig 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 abaixo. 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_STRING
      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.
...

A tabela a seguir descreve os campos do objeto oidc do ClientConfig. A maioria dos campos é opcional. Os campos que você precisa adicionar dependem do provedor de identidade e das opções de configuração escolhidas pelo administrador da plataforma ao configurar o provedor para o GKE Identity Service.

Campo	Obrigatório	Descrição	Formato
Nome	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	No	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 retornado ao registrar o GKE Identity Service com seu provedor de OIDC.	String
clientSecret	Não	Senha secreta entre o aplicativo cliente OIDC e o provedor OIDC.	String
deployCloudConsoleProxy	No	Especifica se um proxy é implantado que permite que o console do Cloud 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	No	A declaração do JWT (nome do campo) que seu provedor usa para retornar os grupos de segurança de uma conta.	String
groupPrefix	No	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.	String do URL
kubectlRedirectURI	Sim	O URL de redirecionamento e a porta usados pela CLI gcloud e especificados pelo administrador da plataforma no registro, geralmente no formato "http://localhost:PORT/callback".	String do URL
scopes	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	No	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 GKE Identity Service usará "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	No	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 GKE Identity Service poderá usar o endpoint userinfo do provedor de identidade para receber informações de grupos quando um usuário fizer login a partir da 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	No	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 concluir o ClientConfig, salve o arquivo, que atualiza o ClientConfig no cluster. Se você cometer algum erro de sintaxe, receberá uma solicitação para reeditar a configuração para corrigi-los.

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.

Azure AD

Essa é a configuração padrão do GKE Identity Service com o Azure AD. O uso dessa configuração permite que o GKE Identity Service receba informações de associação de usuários e grupos do Azure AD, 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 Azure AD (Avançado).

...
spec:
  authentication:
  - name: oidc-azuread
    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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Substitua:

CLIENT_ID: o ID do cliente retornado ao registrar o GKE Identity Service com seu provedor.
CLIENT_SECRET: senha secreta entre o aplicativo cliente OIDC e o provedor OIDC.
TENANT: o tipo de conta do Azure AD 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. Veja detalhes sobre como encontrar esses valores em Encontrar o ID do locatário e o nome de domínio principal do Microsoft Azure AD.
PORT: o número da porta escolhida para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registro.

Azure AD (Avançado)

Essa configuração opcional para o Azure AD permite que o GKE Identity Service 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 Azure AD.

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 Azure AD.

Todos os campos do exemplo a seguir são obrigatórios.

...
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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

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 retornado ao registrar o GKE Identity Service com seu provedor.
CLIENT_SECRET: senha secreta entre o aplicativo cliente OIDC e o provedor OIDC.
TENANT: o tipo de conta do Azure AD 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. Veja detalhes sobre como encontrar esses valores em Encontrar o ID do locatário e o nome de domínio principal do Microsoft Azure AD.
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. No momento, 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 serviço de identidade do GKE usará um valor na ordem "email", "preferred_username" ou "sub" para buscar os detalhes do usuário. Este atributo pode ser usado no GKE Enterprise 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 Anthos Identity Service recupere declarações de usuários e grupos usando um token de acesso e o endpoint userinfo do Okta.

...
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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Limites de acesso de grupos

Para usuários do Okta, o Anthos Identity Service 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.