Use fornecedores de identidade externos para autenticar no GKE

Autopilot Padrão

---

Esta página mostra como configurar a autenticação para clusters do Google Kubernetes Engine (GKE) a partir de fornecedores de identidade (IdPs) externos.

Esta página destina-se a administradores e operadores da plataforma, bem como a administradores de identidade e contas que usam um IdP externo que suporta o OpenID Connect (OIDC) ou a linguagem de marcação de declarações de segurança (SAML) 2.0.

Antes de ler esta página, certifique-se de que está familiarizado com os seguintes conceitos de autenticação e OpenID:

• OAuth 2.0
• SAML 2.0
• OpenID Connect
• Âmbitos e reivindicações da OIDC
• RBAC do Kubernetes

Métodos de autenticação de IdP externo no GKE

Recomendado: federação de identidade da força de trabalho

A federação de identidade da força de trabalho é uma funcionalidade do IAM que lhe permite autenticar-se a partir de qualquer IdP externo que suporte o OIDC ou o SAML 2.0. Google Cloud A Workforce Identity Federation não requer instalação no cluster, funciona com clusters do Autopilot e clusters padrão, e está integrada no Google Cloud. Para ver detalhes, consulte a documentação da IAM acerca da federação de identidades da força de trabalho.

Não recomendado: serviço de identidade para o GKE

Apenas em clusters do GKE Standard, o GKE também suporta o serviço de identidade para o GKE. O serviço de identidade para o GKE está limitado a IdPs OIDC e instala componentes adicionais no seu cluster. O GKE recomenda vivamente a utilização da federação de identidades da força de trabalho em vez do serviço de identidade para o GKE. Tenha também em atenção uma limitação conhecida com o serviço de identidade para o GKE que impede a escala automática.

Aviso: a partir de 1 de julho de 2025, as novas Google Cloud organizações que criar não vão suportar o serviço de identidade para o GKE.

Antes de começar

Antes de começar, certifique-se de que realizou as seguintes tarefas:

• Ative a API Google Kubernetes Engine.
Ative a API Google Kubernetes Engine
• Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute gcloud components update para obter a versão mais recente.
  Nota: para instalações existentes da CLI gcloud, certifique-se de que define a compute/region propriedade. Se usar principalmente clusters zonais, defina o compute/zone. Ao definir uma localização predefinida, pode evitar erros na CLI gcloud, como os seguintes: One of [--zone, --region] must be supplied: Please specify location. Pode ter de especificar a localização em determinados comandos se a localização do seu cluster for diferente da predefinição que definiu.

Considerações

Os sistemas sem interface não são suportados com a federação de identidade da força de trabalho nem com o serviço de identidade para o GKE. Um fluxo de autenticação baseado no navegador pede-lhe o consentimento e a autorização da sua conta de utilizador.

Use a federação de identidade da força de trabalho no GKE

Para usar a federação de identidade da força de trabalho nos seus clusters do GKE, faça o seguinte:

1. Configure a federação de identidade da força de trabalho para a sua organização e IdP externo. Para obter instruções, consulte o artigo Configure a federação de identidade da força de trabalho.
2. Configure o acesso do seu IdP externo à Google Cloud consola da federação de identidade da força de trabalho. Para ver detalhes, consulte o artigo Configure o acesso dos utilizadores à consola (federado).

3. Configure o acesso do utilizador através de um dos seguintes mecanismos de autorização:

   • RBAC do Kubernetes
   • Políticas de permissão do IAM

4. Diga aos seus utilizadores para acederem aos clusters seguindo estes passos:

   1. Inicie sessão na CLI gcloud com a identidade federada.
   2. Configure o kubectl para autenticar um cluster específico executando o comando gcloud container clusters get-credentials.

Configure o acesso dos utilizadores a clusters através do CABF

Google Cloud usa identificadores principais para identificar utilizadores nos seus grupos de identidades da força de trabalho. Pode consultar estes identificadores principais nas suas políticas de RBAC do Kubernetes ou nas políticas de IAM. Pode conceder autorizações a indivíduos ou grupos de utilizadores, como nos seguintes exemplos:

Identidade	Identificador principal
Utilizador único	principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/subject/SUBJECT_ATTRIBUTE_VALUE Substitua o seguinte: WORKFORCE_IDENTITY_POOL: o nome do Workload Identity Pool. SUBJECT_ATTRIBUTE_VALUE: o valor de um atributo na declaração de assunto do token de identidade. Por exemplo, este pode ser o valor do campo NameID numa afirmação SAML 2.0. Por exemplo: principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/[e-mail]
Todos os utilizadores num grupo	principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/group/GROUP_NAME Substitua o seguinte: WORKFORCE_IDENTITY_POOL: o nome do Workload Identity Pool. GROUP_NAME: o nome de um grupo no qual o utilizador de autenticação é membro. A afirmação no seu token do IdP tem de ter um mapeamento de atributos para o atributo Google Cloud google.groups. Por exemplo: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre

Para cada identificador principal suportado pela Workforce Identity Federation, consulte o artigo Representar utilizadores do Workforce Pool em políticas do IAM.

O exemplo seguinte mostra como conceder acesso de leitura apenas ao nível do cluster aos segredos a quaisquer entidades no conjunto de pessoal externo full-time-employees que façam parte do grupo sre no respetivo token do IdP.

1. Guarde o seguinte manifesto ClusterRole como secret-viewer-cluster-role.yaml:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: secret-viewer
   rules:
   - apiGroups: [""]
     resources: ["secrets"]
     verbs: ["get", "watch", "list"]
   

   Qualquer principal ao qual associe esta ClusterRole pode ver segredos.

2. Guarde o seguinte manifesto ClusterRoleBinding como secret-viewer-cluster-role-binding.yaml:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name:  users-view-secrets
   subjects:
   - kind: Group
     name: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: secret-viewer
     apiGroup: rbac.authorization.k8s.io
   

   Esta ClusterRoleBinding concede a ClusterRole secret-viewer a qualquer utilizador que faça parte do grupo sre.

3. Implemente o ClusterRole e o ClusterRoleBinding:

   kubectl apply -f secret-viewer-cluster-role.yaml
   kubectl apply -f secret-viewer-cluster-role-binding.yaml
   

Inicie sessão e autentique-se no cluster

1. Faça com que o utilizador inicie sessão através da CLI do Google Cloud para Google Cloud.

2. O utilizador pode configurar o kubectl para autenticar no cluster através do seguinte:

   gcloud container clusters get-credentials
   

Migre o serviço de identidade para clusters do GKE para a federação de identidade da força de trabalho

Se usar o serviço de identidade para o GKE em clusters do GKE existentes, migre para a Workforce Identity Federation. Estes métodos usam sintaxes diferentes para se referirem aos mesmos principais, conforme mostrado na tabela seguinte:

Sintaxe do serviço de identidade para o GKE	Sintaxe da federação de identidade da força de trabalho
[e-mail]	principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/[e-mail]
sre-group	principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre-group

Para migrar um cluster para usar a federação de identidade da força de trabalho, faça o seguinte:

1. Configure a federação de identidade da força de trabalho para a sua organização e IdP externo. Para obter instruções, consulte o artigo Configure a federação de identidade da força de trabalho.

2. Atualize os manifestos de todas as RoleBindings e ClusterRoleBindings nos seus clusters para usar a sintaxe do identificador da federação de identidade da força de trabalho. Use uma das seguintes opções:

   • Atualizações programáticas: instale e execute o utilitário gke-identity-service-migrator. Para ver instruções, consulte o ficheiro README do repositório GoogleCloudPlatform/gke-utilities.

     Esta utilidade encontra associações RBAC existentes que usam a sintaxe do serviço de identidade para o GKE e cria novos manifestos que usam os identificadores principais da Workforce Identity Federation correspondentes.

   • Atualizações manuais: para cada associação que faça referência a um utilizador ou um grupo autenticado, crie uma cópia separada do ficheiro de manifesto do objeto que use a sintaxe do identificador da Workforce Identity Federation.

3. Aplique os manifestos atualizados para RoleBindings e ClusterRoleBindings ao seu cluster.

4. Teste se os utilizadores conseguem aceder aos mesmos recursos quando se autenticam através da Workforce Identity Federation.

5. Remova as associações RBAC obsoletas do cluster.

6. Desative o serviço de identidade para o GKE.

Use o serviço de identidade para o GKE

Aviso: a partir de 1 de julho de 2025, as novas Google Cloud organizações que criar não vão suportar o serviço de identidade para o GKE.

Para configurar e usar o serviço de identidade para o GKE no seu cluster do modo padrão do GKE, os administradores do cluster fazem o seguinte:

1. Ative o serviço de identidade para o GKE num cluster.
2. Configure o serviço de identidade para o GKE.
3. Crie uma política de CABF para o seu cluster.

Depois de os administradores do cluster configurarem o serviço de identidade para o GKE, os programadores podem iniciar sessão e autenticar-se no cluster.

Objetos do Kubernetes criados pelo serviço de identidade para o GKE

A tabela seguinte descreve os objetos Kubernetes criados quando ativa o serviço de identidade para o GKE num cluster:

Objetos do Kubernetes
anthos-identity-service	Namespace Usado para o serviço de identidade para implementações do GKE.
kube-public	Namespace Usado para o ficheiro de configuração do cliente default.
gke-oidc-envoy	LoadBalancer O ponto final para pedidos OIDC. Externo por predefinição. Se for criado num cluster sem um ponto final de IP externo, o ponto final é interno à nuvem privada virtual do cluster. Criado no espaço de nomes anthos-identity-service.
gke-oidc-service	ClusterIP Facilita a comunicação entre a implementação gke-oidc-envoy e a implementação gke-oidc-service. Criado no espaço de nomes anthos-identity-service.
gke-oidc-envoy	Deployment Executa um proxy exposto ao gke-oidc-envoy LoadBalancer. Comunica com o gke-oidc-service para validar tokens de identidade. Atua como um proxy para o servidor da API Kubernetes e rouba a identidade dos utilizadores quando transmite pedidos ao servidor da API. Criado no espaço de nomes anthos-identity-service.
gke-oidc-service	Deployment Valida tokens de identidade e fornece um webhook de admissão de validação para recursos ClientConfig. Criado no espaço de nomes anthos-identity-service.
gke-oidc-operator	Deployment Reconcilia a configuração do cliente e o gke-oidc-envoy LoadBalancer. Criado no espaço de nomes anthos-identity-service.
gke-oidc-certs	Secret Contém a autoridade de certificação (AC) do cluster e os certificados TLS para o LoadBalancer. Criado no espaço de nomes anthos-identity-service
default	ClientConfig CRD Contém parâmetros OIDC, como o método de autenticação preferencial, a configuração do fornecedor de identidade e os mapeamentos de reivindicações de utilizadores e grupos. Usado para a validação do token de identidade. Usado pelos administradores de clusters para configurar as definições do OIDC antes da distribuição aos programadores. Criado no espaço de nomes kube-public

Ative o serviço de identidade para o GKE num cluster

Por predefinição, a gestão de identidade e de acesso (IAM) está configurada como o fornecedor de identidade para a autenticação de clusters. Se quiser usar o OIDC com fornecedores de identidade de terceiros, pode ativar o serviço de identidade para o GKE em clusters novos ou existentes através da CLI do Google Cloud.

Nota: para que o serviço de identidade para o GKE funcione corretamente, o GKE implementa pods nos seus nós que têm autorizações RBAC> elevadas, como a capacidade de se fazer passar por utilizadores e grupos. Estas autorizações são necessárias para o serviço de identidade para o GKE facilitar a validação de identidade e a comunicação com base na sua configuração.

Ative o serviço de identidade para o GKE num novo cluster

Para criar um cluster com o serviço de identidade para o GKE ativado, execute o seguinte comando:

gcloud container clusters create CLUSTER_NAME \
    --enable-identity-service

Substitua CLUSTER_NAME pelo nome do novo cluster.

Ative o serviço de identidade para o GKE num cluster existente

Para ativar o serviço de identidade para o GKE num cluster existente, execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    --enable-identity-service

Substitua CLUSTER_NAME pelo nome do seu cluster.

Configure o serviço de identidade para o GKE

Pode configurar os parâmetros do serviço de identidade para o GKE transferindo e modificando o default ClientConfig.

1. Transfira o defaultClientConfig:

   kubectl get clientconfig default -n kube-public -o yaml > client-config.yaml
   

2. Atualize a secção spec.authentication com as suas definições preferenciais:

   apiVersion: authentication.gke.io/v2alpha1
   kind: ClientConfig
   metadata:
     name: default
     namespace: kube-public
   spec:
     name: cluster-name
     server: https://192.168.0.1:6443
     authentication:
     - name: oidc
       oidc:
         clientID: CLIENT_ID
         certificateAuthorityData: OIDC_PROVIDER_CERTIFICATE
         extraParams: EXTRA_PARAMS
         issuerURI:  ISSUER_URI
         cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
         kubectlRedirectURI: KUBECTL_REDIRECT_URL
         scopes: SCOPES
         userClaim: USER
         groupsClaim: GROUPS
         userPrefix: USER_PREFIX
         groupPrefix: GROUP_PREFIX
   

   Substitua o seguinte:

   • CLIENT_ID: o ID da aplicação cliente que faz pedidos de autenticação ao fornecedor de OIDC.
   • OIDC_PROVIDER_CERTIFICATE: (Opcional) um certificado PEM para o fornecedor de OIDC. Este campo pode ser útil se o seu fornecedor de OIDC usar certificados autoassinados. O serviço de identidade para o GKE inclui um conjunto de raízes públicas por predefinição.
   • EXTRA_PARAMS: parâmetros de chave-valor adicionais a enviar ao fornecedor de OIDC.
     • Para autorizar grupos, use resource=token-groups-claim.
     • Para autenticar o Microsoft Azure e o Okta, use prompt=consent.
     • Para o Cloud ID, use prompt=consent,access_type=offline.
   • ISSUER_URI: o URL para enviar pedidos de autorização OIDC, como https://example.com/adfs. O servidor da API Kubernetes usa este URL para descobrir chaves públicas para validar tokens. O URI tem de usar HTTPS. Para o Cloud ID, use https://accounts.google.com.
   • KUBECTL_REDIRECT_URL: o URL de redirecionamento que kubectl oidc login usa para autorização. Normalmente, tem o formato http://localhost:PORT/callback, em que PORT é qualquer porta superior a 1024 que vai estar disponível nas estações de trabalho dos programadores, por exemplo, http://localhost:10000/callback. Tem de registar o URL junto do seu fornecedor de OIDC como um URL de redirecionamento autorizado para a aplicação cliente. Se usar a identidade Google como fornecedor de OIDC, leia o artigo Defina um URI de redirecionamento para ver instruções.
   • SCOPES: os âmbitos adicionais a enviar para o fornecedor de OIDC.
     • O Microsoft Azure e o Okta requerem o âmbito offline_access.
     • Para o Cloud Identity, use openid, email para obter tokens de ID que contêm o endereço de email na reivindicação email.
   • USER: a reivindicação do utilizador do token de identidade.
   • GROUPS: a reivindicação de grupo do token de identidade.
   • USER_PREFIX: prefixo anteposto às reivindicações do utilizador para evitar conflitos com nomes existentes. Por predefinição, é anexado um prefixo do emissor ao userID fornecido ao servidor da API Kubernetes (a menos que a reivindicação do utilizador seja email). O identificador do utilizador resultante é ISSUER_URI#USER. Recomendamos que use um prefixo, mas pode desativá-lo definindo USER_PREFIX como -.
   • GROUP_PREFIX: prefixo anteposto às reivindicações de grupo para evitar conflitos com nomes existentes. Por exemplo, se tiver dois grupos denominados foobar, adicione um prefixo gid-. O grupo resultante é gid-foobar.

3. Aplique a configuração atualizada:

   kubectl apply -f client-config.yaml
   

   Depois de aplicar esta configuração, o serviço de identidade para o GKE é executado no cluster e processa pedidos atrás do balanceador de carga gke-oidc-envoy. O endereço IP no campo spec.server tem de ser o endereço IP do equilibrador de carga. Se alterar o campo spec.server, os comandos kubectl podem falhar.

4. Crie uma cópia do ficheiro de configuração client-config.yaml:

   cp client-config.yaml login-config.yaml
   

5. Atualize o ficheiro de configuração login-config.yaml com a definição clientSecret na secção spec.authentication.oidc.

   clientSecret: CLIENT_SECRET
   

   Substitua CLIENT_SECRET pelo segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.

6. Distribua o ficheiro login-config.yaml atualizado aos seus programadores.

Configure o serviço de identidade para o GKE em clusters com políticas rigorosas

Para configurar o serviço de identidade para o GKE de modo a funcionar como esperado em clusters que tenham políticas de rede rigorosas implementadas, faça o seguinte:

1. Adicione uma regra de firewall para a porta TCP 15000 para permitir que o seu plano de controlo comunique com o webhook de validação ClientConfig.
2. Se o gke-oidc-envoy for criado como um balanceador de carga interno, exponha-o na sua VPC.
3. Se tiver políticas que negam o tráfego no cluster, adicione uma regra de firewall para a porta TCP 8443 para permitir que a implementação gke-oidc-envoy comunique com a implementação gke-oidc-service.

A versão 0.2.20 e posteriores do componente do serviço de identidade para o GKE não usa a porta TCP 15000. Se a versão do componente for 0.2.20 ou posterior, não precisa de adicionar uma regra de firewall para a porta 15000. Para verificar a versão do componente, execute o seguinte comando:

kubectl describe deployment gke-oidc-envoy -n anthos-identity-service \
    | grep "components.gke.io/component-name: gke-oidc" -A1

Adicione propriedades personalizadas ao equilibrador de carga

Depois de configurar o serviço de identidade para o GKE, pode adicionar anotações e propriedades personalizadas, como um endereço IP estático, ao gke-oidc-envoyequilibrador de carga. Para editar o serviço gke-oidc-envoy, execute o seguinte comando:

kubectl edit service gke-oidc-envoy -n anthos-identity-service

Consulte os parâmetros do serviço LoadBalancer para mais informações sobre a configuração do balanceamento de carga de TCP/UDP para o GKE.

Crie uma política de RBAC para o seu cluster

Os administradores podem usar o controlo de acesso baseado em funções (RBAC) do Kubernetes para conceder acesso a utilizadores autenticados do cluster. Para configurar o RBAC para o seu cluster, tem de conceder funções RBAC a cada programador. Para conceder acesso a recursos num espaço de nomes específico, crie uma função e uma RoleBinding. Para conceder acesso a recursos num cluster inteiro, crie um ClusterRole e um ClusterRoleBinding.

Por exemplo, considere um utilizador que precisa de ver todos os objetos Secret no cluster. Os passos seguintes concedem as funções RBAC necessárias a este utilizador.

1. Guarde o seguinte manifesto ClusterRole como secret-viewer-cluster-role.yaml. Uma pessoa à qual é concedido este papel pode obter, ver e listar qualquer segredo no cluster.

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: secret-viewer
   rules:
   - apiGroups: [""]
     # The resource type for which access is granted
     resources: ["secrets"]
     # The permissions granted by the ClusterRole
     verbs: ["get", "watch", "list"]
   

2. Aplique o manifesto ClusterRole:

   kubectl apply -f secret-viewer-cluster-role.yaml
   

3. Guarde o seguinte manifesto ClusterRoleBinding como secret-viewer-cluster-role-binding.yaml. A associação concede a função secret-viewer a um nome de utilizador definido no ficheiro de configuração do cliente.

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name:  people-who-view-secrets
   subjects:
   - kind: User
     name: ISSUER_URI#USER
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: secret-viewer
     apiGroup: rbac.authorization.k8s.io
   

   Substitua o seguinte:

   • ISSUER_URI: o URI do emissor de spec.authentication.oidc.issuerURI no ficheiro de configuração do cliente.
   • USER: o identificador do utilizador no token no nome da reivindicação configurado em spec.authentication.oidc.userClaim no ficheiro de configuração do cliente.

4. Aplique o manifesto ClusterRoleBinding:

   kubectl apply -f secret-viewer-cluster-role-binding.yaml
   

Inicie sessão e autentique-se no cluster

Enquanto programador que recebe o ficheiro de configuração do OIDC do seu administrador, pode autenticar-se nos seus clusters.

1. Transfira o ficheiro login-config.yaml fornecido pelo seu administrador.

2. Instale o SDK da CLI Google Cloud, que oferece um componente OIDC separado. Pode instalá-lo executando o seguinte comando:

   gcloud components install kubectl-oidc
   

3. Autentique-se no cluster:

   kubectl oidc login --cluster=CLUSTER_NAME --login-config=login-config.yaml
   

   É aberto um navegador de Internet para concluir o processo de autenticação.

4. Depois de se autenticar, pode executar comandos kubectl, por exemplo:

   kubectl get pods
   

Desative o serviço de identidade para o GKE

Pode desativar o serviço de identidade para o GKE com a CLI gcloud. Para desativar o serviço de identidade para o GKE, execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    --no-enable-identity-service

Limitações conhecidas

O componente gke-oidc-envoy, que é responsável pela autenticação no cluster através do serviço de identidade para o GKE, tem um número fixo de réplicas. Isto significa que não é dimensionado automaticamente para processar o aumento do tráfego. Nos clusters regionais, este componente é implementado com três réplicas.

Não pode dimensionar diretamente a implementação gke-oidc-envoy. Recomendamos vivamente que migre para a federação de identidade da força de trabalho para uma solução escalável e mais robusta.

O que se segue?

• Saiba mais acerca da federação de identidades da força de trabalho.
• Saiba mais sobre a implementação de cargas de trabalho.