Usar provedores de identidade externos para autenticar no GKE

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

Esta página é destinada a administradores e operadores de plataforma e administradores de identidade e conta que usam um IdP externo compatível com OpenID Connect (OIDC) ou Security Assertion Markup Language (SAML) 2.0.

Antes de ler esta página, 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 fazer autenticação no Google Cloud de qualquer IdP externo compatível com OIDC ou SAML 2.0. A federação de identidade de colaboradores não exige instalação no cluster, funciona com clusters do Autopilot e Standard e está 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

Somente em clusters do GKE Standard, o GKE também oferece suporte ao serviço de identidade do GKE. O serviço de identidade para o GKE é limitado a provedores de identidade OIDC e instala componentes adicionais no cluster. O GKE recomenda usar a federação de identidade de colaboradores em vez do serviço de identidade para o GKE.

Antes de começar

Antes de começar, veja se você realizou as seguintes tarefas:

• Ative a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a CLI do Google Cloud para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a gcloud CLI anteriormente, instale a versão mais recente executando gcloud components update.

Considerações

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

Usar 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 clusters do GKE, faça o seguinte:

1. Configure a federação de identidade de colaboradores para sua organização e IdP externo. Para instruções, consulte Configurar a federação de identidade de colaboradores.
2. Configure o acesso do seu 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 aos clusters usando o RBAC

OGoogle Cloud usa identificadores principais para identificar usuários nos seus pools de identidades de força de trabalho. É possível consultar esses identificadores principais nas políticas de RBAC do Kubernetes ou nas políticas do IAM. Você pode conceder permissões a pessoas ou grupos de usuários, como nos exemplos a seguir:

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/subject/SUBJECT_ATTRIBUTE_VALUE

principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/amal@example.com

principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/group/GROUP_NAME

principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre

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

O exemplo a seguir mostra como conceder acesso de leitura em todo o cluster aos Secrets para qualquer entidade no pool de força de trabalho full-time-employees que tenha o atributo access_level="sensitive" 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 a que você vincular esse ClusterRole poderá ver secrets.

2. Salve 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/attribute.access_level/sensitive
     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 tenha o atributo access_level="sensitive".

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 CLI do Google Cloud para Google Cloud.

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

   gcloud container clusters get-credentials
   

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

Se você usa o serviço de identidade para GKE em clusters do GKE existentes, migre para a Federação de Identidade da Força de Trabalho. Esses métodos usam sintaxes diferentes para se referir aos mesmos princípios, como mostrado na tabela a seguir:

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

1. Configure a federação de identidade de colaboradores para sua organização e IdP externo. Para instruções, consulte Configurar a federação de identidade de colaboradores.

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

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

     Essa ferramenta encontra vinculações de RBAC atuais que usam a sintaxe do serviço de identidade para o GKE e cria novos manifestos que usam os identificadores principais correspondentes da federação de identidade de colaboradores.

   • Atualizações manuais: para cada vinculação que faz referência a um usuário ou grupo autenticado, crie uma cópia separada do arquivo de manifesto do objeto que usa a sintaxe do identificador da Federação de identidade da força de trabalho.

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

4. Teste se os usuários podem acessar os mesmos recursos ao se autenticarem usando a Federação de Identidade de Colaboradores.

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

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

Usar o serviço de identidade para o 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:

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.

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 da API Kubernetes usa esse URL para descobrir chaves públicas de verificação de 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. Registre o URL no seu provedor do OIDC como um URL de redirecionamento autorizado para o aplicativo do 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 da 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 do cliente e o provedor do 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 gcloud CLI. Para desativar o serviço de identidade para o GKE, execute o seguinte comando:

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

A seguir

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