Usar provedores de identidade externos para autenticar no GKE

Autopilot Standard

Nesta página, mostramos como configurar a autenticação em clusters do Google Kubernetes Engine (GKE) de provedores de identidade externa (IdPs).

Esta página é destinada a administradores e operadores de plataforma e administradores de identidade e conta que usam um IdP externo compatível com o OpenID Connect (OIDC) ou a Linguagem de marcação para autorização de segurança (SAML) 2.0.

Antes de ler este documento, você precisa conhecer os seguintes conceitos de autenticação e OpenID:

• OAuth 2.0
• SAML 2.0
• OpenID Connect
• Escopos e declarações do OIDC
• RBAC do Kubernetes

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

Recomendado: federação de identidade de colaboradores

A federação de identidade de colaboradores é um recurso do IAM que permite autenticar no Google Cloud usando qualquer IdP externo compatível com OIDC ou SAML 2.0. A federação de identidade de colaboradores não exige nenhuma instalação no cluster, funciona com clusters do Autopilot e clusters Standard e é integrada ao Google Cloud. Para mais detalhes, consulte a documentação do IAM sobre a federação de identidade de colaboradores.

Não recomendado: serviço de identidade para o GKE (descontinuado)

Atenção: a partir de 1º de julho de 2026, o serviço de identidade para GKE será descontinuado e não será mais compatível com o GKE versão 1.37 e mais recentes. Para mais informações, consulte Descontinuação do serviço de identidade para GKE.

Somente em clusters do GKE Standard, o GKE também oferece suporte ao serviço de identidade para GKE. O serviço de identidade para o GKE é limitado a IdPs do OIDC e instala componentes adicionais no cluster. O GKE recomenda o uso da federação de identidade de colaboradores em vez do serviço de identidade para o GKE. Observe também uma limitação conhecida do serviço de identidade para GKE que impede o escalonamento automático.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ative a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Para usar a Google Cloud CLI nesta tarefa, instale e inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.
  Observação: em instalações prévias da CLI gcloud, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na CLI gcloud como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

Considerações

Os sistemas headless não são compatíveis com a federação de identidade de colaboradores e o serviço de identidade para o GKE. Um fluxo de autenticação baseado em navegador solicita seu consentimento e autoriza sua conta de usuário.

Usar a federação de identidade de colaboradores no GKE

Para usar a federação de identidade de colaboradores nos clusters do GKE, faça o seguinte:

1. Configure a federação de identidade de colaboradores para sua organização e o IdP externo. Para instruções, consulte Configurar a federação de identidade de colaboradores.
2. Configure o acesso do IdP externo ao console da Google Cloud federação de identidade de colaboradores. Para mais detalhes, consulte Configurar o acesso do usuário ao console (federado).

3. Configure o acesso do usuário usando um dos seguintes mecanismos de autorização:

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

4. Peça para os usuários acessarem os clusters seguindo estas etapas:

   1. Faça login na CLI gcloud com a identidade federada.
   2. Configure o kubectl para autenticar em um cluster específico executando gcloud container clusters get-credentials.

Configurar o acesso do usuário a clusters usando o RBAC

OGoogle Cloud usa identificadores de principal para identificar usuários nos seus pools de identidades de colaboradores. É possível consultar esses identificadores principais nas políticas de RBAC do Kubernetes ou do IAM para conceder permissões a indivíduos ou grupos de usuários. Com o RBAC, não é possível referenciar outras declarações personalizadas que os tokens do IdP contêm. O RBAC é compatível com identificadores principais apenas para usuários e grupos.

A tabela a seguir mostra exemplos de identificadores principais para usuários únicos e para grupos:

Identidade	Identificador do principal
Único usuário	principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/subject/SUBJECT_ATTRIBUTE_VALUE Substitua: WORKFORCE_IDENTITY_POOL: o nome do pool de identidade da força de trabalho. SUBJECT_ATTRIBUTE_VALUE: o valor de um atributo na declaração de assunto do token de identidade. Por exemplo, pode ser o valor do campo NameID em uma declaração SAML 2.0. Exemplo: principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/[e-mail]
Todos os usuários em um grupo	principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/group/GROUP_NAME Substitua: WORKFORCE_IDENTITY_POOL: o nome do pool de identidade de colaboradores. GROUP_NAME: o nome de um grupo em que o usuário que faz a autenticação é membro. A declaração no token do IdP precisa ter um mapeamento de atributos para o atributo Google Cloud google.groups. Exemplo: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre

Para cada identificador de principal compatível com a federação de identidade de colaboradores, consulte Representar usuários do pool de colaboradores nas políticas do IAM.

O exemplo a seguir mostra como conceder acesso somente leitura em todo o cluster em Secrets a qualquer entidade no pool de colaboradores full-time-employees que faça parte do grupo sre no token do IdP.

1. Salve 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 você vincular esse ClusterRole poderá ver os Secrets.

2. Salve o manifesto ClusterRoleBinding a seguir 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
   

   Esse ClusterRoleBinding concede o ClusterRole secret-viewer a qualquer usuário que faça parte do grupo sre.

3. Implante o ClusterRole e o ClusterRoleBinding:

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

Fazer login e autenticar no cluster

1. Peça para o usuário fazer login usando a Google Cloud CLI.

2. O usuário pode configurar o kubectl para autenticar no cluster usando o seguinte:

   gcloud container clusters get-credentials
   

Usar o serviço de identidade para o GKE

Atenção: a partir de 1º de julho de 2026, o serviço de identidade para GKE será descontinuado e não será mais compatível com o GKE versão 1.37 e mais recentes. Em vez disso, use a federação de identidade de colaboradores. Para mais informações, consulte Descontinuação do serviço de identidade para GKE.

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

1. Habilitar o serviço de identidade para o GKE em um cluster.
2. Configurar o serviço de identidade para o GKE.
3. Criar uma política de RBAC para o cluster.

Depois que os administradores do cluster configurarem o serviço de identidade para o GKE, os desenvolvedores poderão fazer login e autenticar no cluster.

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

Na tabela a seguir, descrevemos os objetos do Kubernetes criados quando você habilita o serviço de identidade para o GKE em um cluster:

Objetos do Kubernetes
anthos-identity-service	Namespace Usado no serviço de identidade para implantações do GKE.
kube-public	Namespace Usado para o default arquivo de configuração do cliente.
gke-oidc-envoy	LoadBalancer O endpoint para solicitações de OIDC. Externo por padrão. Se criado em um cluster sem endpoint de IP externo, o endpoint será interno à nuvem privada virtual do cluster. Criado no namespace anthos-identity-service.
gke-oidc-service	ClusterIP Facilita a comunicação entre a implantação gke-oidc-envoy e a implantação gke-oidc-service. Criado no namespace anthos-identity-service.
gke-oidc-envoy	Deployment Executa um proxy exposto ao gke-oidc-envoyLoadBalancer. Se comunica com gke-oidc-service para validar tokens de identidade. Atua como um proxy para o servidor de API Kubernetes e representa os usuários ao transmitir solicitações para o servidor de API. Criado no anthos-identity-servicenamespace.
gke-oidc-service	Deployment Valida os tokens de identidade e fornece um webhook de admissão de validação para recursos ClientConfig. Criado no namespace anthos-identity-service.
gke-oidc-operator	Deployment Reconcilia a configuração do cliente e o LoadBalancer gke-oidc-envoy. Criado no namespace anthos-identity-service.
gke-oidc-certs	Secret Contém a autoridade certificadora (CA) do cluster e os certificados TLS do LoadBalancer. Criado no namespace anthos-identity-service
default	ClientConfig CRD Contém parâmetros do OIDC, como método de autenticação de preferência, configuração do provedor de identidade e mapeamentos de declarações de usuário e grupo. Usado para validação de token de identidade. Usado pelos administradores de cluster para definir as configurações do OIDC antes de distribuir para os desenvolvedores. Criado no namespace kube-public

Habilitar o serviço de identidade para o GKE em um cluster

Por padrão, o gerenciamento de identidade e acesso (IAM, na sigla em inglês) é configurado como o provedor de identidade para a autenticação do cluster. Se você quiser usar o OIDC com provedores de identidade de terceiros, habilite o serviço de identidade para o GKE em clusters novos ou atuais usando a Google Cloud CLI.

Observação:Para que o serviço de identidade do GKE funcione corretamente, o GKE implementa pods nos nós com Permissões do RBAC elevadas, como a capacidade de representar usuários e grupos. Essas permissões são necessárias para que o Identity Service para GKE facilite a validação e a comunicação de identidade com base na sua configuração.

Habilitar o serviço de identidade para o GKE em um novo cluster

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

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

Substitua CLUSTER_NAME pelo nome do novo bucket.

Habilitar o serviço de identidade para o GKE em um cluster atual

Para habilitar o serviço de identidade para o GKE em um cluster atual, execute este comando

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

Substitua CLUSTER_NAME pelo nome do cluster.

Configurar o serviço de identidade para o GKE

É possível configurar os parâmetros do serviço de identidade para o GKE fazendo o download e modificando o ClientConfig default.

1. Faça o download do ClientConfig default:

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

2. Atualize a seção spec.authentication com as configurações que preferir:

   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:

   • CLIENT_ID: ID do aplicativo cliente que faz solicitações de autenticação para o provedor OIDC.
   • OIDC_PROVIDER_CERTIFICATE: (opcional) um certificado PEM para o provedor OIDC. Esse campo pode ser útil caso o provedor OIDC use certificados autoassinados. O serviço de identidade para GKE inclui um conjunto de raízes públicas por padrão.
   • EXTRA_PARAMS: parâmetros de chave-valor extras a serem enviados ao provedor OpenID.
     • Para autorizar grupos, use resource=token-groups-claim.
     • Para autenticar o Microsoft Azure e o Okta, use prompt=consent.
     • Para o Cloud Identity, use prompt=consent,access_type=offline.
   • ISSUER_URI: o URL para enviar solicitações de autorização do OIDC, como https://example.com/adfs. O servidor de API Kubernetes usa esse URL para descobrir chaves públicas para verificar tokens. O URI precisa usar HTTPS. Para o Cloud Identity, use https://accounts.google.com.
   • KUBECTL_REDIRECT_URL: o URL de redirecionamento que kubectl oidc login usa para autorização. Normalmente, é no formato http://localhost:PORT/callback, em que PORT é qualquer porta maior que 1024 que estará disponível em estações de trabalho do desenvolvedor, por exemplo, http://localhost:10000/callback de dados. Registre o URL no seu provedor do OIDC como um URL de redirecionamento autorizado para o aplicativo cliente. Se você usa o Google Identity como seu provedor do OIDC, leia Definir um URI de redirecionamento para instruções.
   • SCOPES: outros escopos a serem enviados ao provedor do OIDC.
     • O Microsoft Azure e o Okta exigem o offline_access escopo.
     • Para o Cloud Identity, use openid, email para conseguir os tokens de ID que contêm o endereço de e-mail na email declaração.
   • USER: a declaração do usuário do token de identidade.
   • GROUPS: a declaração do grupo do token de identidade.
   • USER_PREFIX: prefixo anexado a declarações de usuários para evitar conflitos com nomes atuais. Por padrão, um prefixo de emissor é anexado ao userID fornecido ao servidor de API Kubernetes (a menos que a declaração do usuário seja email). O identificador de usuário resultante é ISSUER_URI#USER. Recomendamos o uso de um prefixo, mas é possível desativá-lo definindo USER_PREFIX como -.
   • GROUP_PREFIX: prefixo anexado a declarações de grupos para evitar conflitos com nomes atuais. Por exemplo, se você tiver dois grupos chamados 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 essa configuração, o serviço de identidade para o GKE será executado dentro do cluster e atenderá às solicitações por trás do balanceador de carga gke-oidc-envoy. O endereço IP no campo spec.server precisa ser o endereço IP do balanceador de carga. Se você alterar o campo spec.server, os comandos kubectl podem falhar.

4. Faça uma cópia do arquivo de configuração client-config.yaml:

   cp client-config.yaml login-config.yaml
   

5. Atualize o arquivo de configuração login-config.yaml novamente com a configuração clientSecret na seção spec.authentication.oidc.

   clientSecret: CLIENT_SECRET
   

   Substitua CLIENT_SECRET pela chave secreta compartilhada entre o aplicativo cliente e o provedor OIDC.

6. Distribua o arquivo login-config.yaml atualizado para seus desenvolvedores.

Configurar o serviço de identidade para o GKE em clusters com políticas rígidas

Para configurar o serviço de identidade para o GKE para que funcione conforme o esperado em clusters com políticas de rede rígidas em vigor, faça o seguinte:

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

O Identity Service para GKE versão 0.2.20 e posterior não usa a porta TCP 15000. Se a versão do componente for 0.2.20 ou posterior, não será necessário 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

Adicionar propriedades personalizadas ao balanceador de carga

Depois de configurar o serviço de identidade para o GKE, é possível adicionar anotações e propriedades personalizadas, como um endereço IP estático, ao balanceador de carga gke-oidc-envoy. Para criar o serviço gke-oidc-envoy, execute este comando:

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

Consulte Parâmetros de serviço do LoadBalancer para saber como configurar o balanceamento de carga TCP/UDP para o GKE.

Criar uma política de RBAC para o cluster

Os administradores podem usar o controle de acesso baseado em papéis (RBAC) do Kubernetes para conceder acesso a usuários de cluster autenticados. Para configurar o RBAC no cluster, os administradores precisam conceder papéis do RBAC para cada desenvolvedor. Para conceder acesso a recursos em um namespace específico, crie um Papel e um RoleBinding . Para conceder acesso a recursos em um cluster inteiro, crie um ClusterRole e um ClusterRoleBinding.

Por exemplo, considere um usuário que precisa visualizar todos os objetos de secret no cluster. As etapas a seguir concedem os papéis do RBAC necessários a esse usuário.

1. Salve o seguinte manifesto ClusterRole como secret-viewer-cluster-role.yaml. Uma pessoa que tem esse papel pode receber, observar e listar qualquer secret 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. Salve o manifesto ClusterRoleBinding a seguir como secret-viewer-cluster-role-binding.yaml. A vinculação concede o papel secret-viewer a um nome de usuário definido no arquivo 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:

   • ISSUER_URI: o URI do emissor de spec.authentication.oidc.issuerURI no arquivo de configuração do cliente.
   • USER: o identificador do usuário no token com o nome da declaração configurado em spec.authentication.oidc.userClaim no arquivo de configuração do cliente.

4. Aplique o manifesto ClusterRoleBinding:

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

Fazer login e autenticar no cluster

Como desenvolvedor que recebe o arquivo de configuração do OIDC do administrador, é possível fazer a autenticação nos clusters.

1. Faça o download do arquivo login-config.yaml fornecido pelo administrador.

2. Instale o SDK da Google Cloud CLI, que oferece um componente OIDC separado. Para isso, execute o seguinte comando:

   gcloud components install kubectl-oidc
   

3. Autentique-se no cluster:

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

   Um navegador da Web é aberto para concluir o processo de autenticação.

4. Após a autenticação, será possível executar comandos kubectl, por exemplo:

   kubectl get pods
   

Desativar o serviço de identidade para o GKE

É possível 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, responsável por autenticar no cluster usando o serviço de identidade para GKE, tem um número fixo de réplicas. Isso significa que ele não faz o escalonamento automático para lidar com o aumento do tráfego. Em clusters regionais, esse componente é implantado com três réplicas.

Não é possível escalonar diretamente a implantação gke-oidc-envoy. Recomendamos migrar para a federação de identidade de colaboradores para ter uma solução escalonável e mais robusta.

A seguir

• Saiba mais sobre a federação de identidade de colaboradores.
• Saiba mais sobre Como implantar cargas de trabalho.