Configurar o gateway do Connect com identidades de terceiros

Este guia é destinado a administradores de plataformas que precisam configurar o gateway do Connect em um projeto com usuários que não têm identidades do Google e não pertencem ao Google Workspace. Neste guia, essas identidades são chamadas de "identidades de terceiros". Antes de ler este guia, você precisa se familiarizar com os conceitos na Visão geral do gateway do Connect. Para autorizar contas individuais do Google, consulte Como configurar o gateway do Connect. Para receber suporte aos Grupos do Google, consulte Como configurar o gateway do Connect com os Grupos do Google.

Com a configuração neste guia, os usuários podem fazer login nos clusters da frota usando a CLI do Google Cloud, o gateway do Connect e o console do Google Cloud.

Tipos de cluster compatíveis

É possível configurar o controle de acesso com identidades de terceiros por meio do gateway do Connect para os seguintes tipos de cluster registrados:

• Clusters do GKE
• Google Distributed Cloud (somente software) no VMware e bare metal do Anthos (GKE Enterprise) 1.13 e versões mais recentes
• GKE na AWS e GKE no Azure do Kubernetes versão 1.25 e posterior.
• Clusters anexados do Anthos GKE Enterprise 1.16 e versões mais recentes

Se você precisar fazer upgrade de clusters no local para usar esse recurso, consulte Como fazer upgrade de clusters do GKE Enterprise para o VMWare e Como fazer upgrade de clusters do GKE Enterprise em bare metal.

Se você tiver um caso de uso para ambientes de clusters do GKE diferentes dos listados acima, entre em contato com o Cloud Customer Care ou a equipe de gateway do Connect.

Como funciona

Conforme descrito na visão geral, talvez os usuários estejam usando provedores de identidade que não são o Google Workspace nem o Cloud Identity. Com a federação de identidade de força de trabalho, os usuários podem usar provedores de identidade de terceiros, como o Okta ou o Azure Active Directory, para ter acesso aos clusters pelo gateway do Connect. Ao contrário das Contas do Google, os usuários terceirizados são representados por um principal do Identity and Access Management (IAM) que segue o formato:

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE

• O WORKFORCE_POOL_ID é o nome do pool da força de trabalho que contém o provedor de identidade de terceiros relevante.

• O SUBJECT_VALUE é o mapeamento da identidade de terceiros para um assunto do Google.

Para grupos de terceiros, o principal do IAM segue o formato:

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_VALUE

O diagrama a seguir mostra um fluxo típico de um usuário de terceiros que faz a autenticação e executa comandos em um cluster com esse serviço ativado. Para que esse fluxo funcione, uma política de controle de acesso baseado em função (RBAC) precisa ser aplicada ao cluster para o usuário ou um grupo.

Para usuários individuais, uma política de RBAC que usa o nome completo do principal do IAM do usuário precisa existir no cluster.

Se você estiver usando a funcionalidade de grupo, uma política de RBAC que use o nome completo do principal do IAM precisa existir no cluster para um grupo que:

1. Contém o usuário [e-mail] como membro.

2. Está incluído no mapeamento de um provedor de identidade em um pool de força de trabalho que está na organização do Google Cloud de Alice.

Observação: o serviço de identidade do GKE precisa ser configurado para que a funcionalidade de grupos de terceiros funcione em clusters de membros da frota fora do Google Cloud.

1. O usuário [e-mail] faz login na gcloud com a identidade de terceiros usando o login baseado em navegador de terceiros. Para usar o cluster na linha de comando, o usuário recebe o gateway kubeconfig do cluster, conforme descrito em Como usar o gateway do Connect.
2. O usuário envia uma solicitação executando um comando kubectl ou abrindo as páginas Cargas de trabalho ou Navegador de objetos do Google Kubernetes Engine no Console do Google Cloud.
3. A solicitação é recebida pelo gateway do Connect, que processa a autenticação de terceiros usando a federação de identidade da força de trabalho.
4. O gateway do Connect realiza uma verificação de autorização com o IAM.
5. O serviço do Connect encaminha a solicitação ao agente do Connect em execução no cluster. A solicitação é acompanhada com as informações de credencial do usuário para uso na autenticação e autorização no cluster.
6. O agente do Connect encaminha a solicitação para o servidor da API Kubernetes.
7. O servidor da API Kubernetes encaminha a solicitação para o GKE Identity Service, que valida a solicitação.
8. O serviço de identidade do GKE retorna as informações de grupo e usuário de terceiros para o servidor da API Kubernetes. O servidor da API Kubernetes pode usar essas informações para autorizar a solicitação com base nas políticas de RBAC configuradas do cluster.

Antes de começar

• Verifique se você tem as seguintes ferramentas de linha de comando instaladas:

  • A versão mais recente da Google Cloud CLI, a ferramenta de linha de comando para interagir com o Google Cloud.
  • A ferramenta de linha de comando do Kubernetes, kubectl, para interagir com os clusters.

  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 usar com seu projeto.

• Este guia presume que você tem roles/owner no seu projeto. Se você não for proprietário do projeto, talvez precise de outras permissões para executar algumas das etapas de configuração.

• Para clusters fora do Google Cloud, o serviço de identidade do GKE precisa chamar as APIs do Google do cluster para concluir a autenticação. Verifique se a política de rede exige que tráfego de saída passe por um proxy.

Configurar mapeamentos de atributos de identidade de terceiros usando a identidade da força de trabalho

Verifique se há um pool de força de trabalho e um provedor de identidade configurados para sua organização do Google Cloud seguindo as instruções correspondentes ao provedor de identidade:

• Azure AD
• Okta
• Outro OIDC ou SAML 2.0

Observação: há um limite de mapeamento de atributos de 4 kilobytes, o que inclui grupos para cada provedor de identidade.

.

ativar APIs

Para adicionar o gateway ao seu projeto, ative a API do gateway do Connect e as APIs de dependência necessárias. Se os usuários quiserem se autenticarem apenas em clusters usando o console do Google Cloud, você não precisará ativar connectgateway.googleapis.com, mas precisará ativar as APIs restantes.

gcloud services enable --project=PROJECT_ID  \
connectgateway.googleapis.com \
anthos.googleapis.com \
gkeconnect.googleapis.com \
gkehub.googleapis.com \
cloudresourcemanager.googleapis.com

Observação: se você não for proprietário de um projeto, precisará ter a permissão serviceusage.services.enable para ativar as APIs para ele.

Configurar o serviço de identidade do GKE

O recurso de suporte de identidade de terceiros do gateway do Connect usa o serviço de identidade do GKE para receber informações de associação aos grupos do Google. Saiba mais sobre o serviço de identidade do GKE em Introdução ao serviço de identidade do GKE.

Se você usa clusters do GKE com o gateway, não precisa configurar o GKE Identity Service para usar o suporte de identidade de terceiros. Em vez disso, siga as instruções em Configurar Grupos do Google para RBAC e continue em Conceder papéis do IAM para conceder acesso aos clusters pelo gateway.

Se você estiver usando clusters anexados do GKE com o gateway, o serviço de identidade do GKE não será necessário para oferecer suporte a identidades de terceiros. Siga as instruções para o tipo de cluster escolhido para configurar o suporte à identidade de terceiros:

• Conectar-se ao cluster anexado do EKS
• Conectar-se ao cluster anexado do AKS
• Conectar-se a outros tipos de cluster

Verifique se o serviço de identidade do GKE está instalado

O serviço de identidade do GKE é instalado por padrão nos clusters do GKE a partir da versão 1.7, embora a compatibilidade com identidades de terceiros exija a versão 1.13 ou superior. Para confirmar se ele está instalado corretamente no cluster, execute o seguinte comando:

kubectl --kubeconfig CLUSTER_KUBECONFIG get all -n anthos-identity-service

Substitua CLUSTER_KUBECONFIG pelo caminho para o kubeconfig do cluster.

Configurar a compatibilidade com a identidade de terceiros para grupos

Se o cluster ou a frota já estiver configurado para a compatibilidade com Grupos do Google, não haverá outras etapas. Você poderá pular para Conceder papéis do IAM a usuários e grupos de terceiros.

Se você estiver usando o Google Distributed Cloud no VMware ou em bare metal, a maneira de configurar o serviço de identidade do GKE determina como é necessário configurar o recurso de grupos de terceiros.

Se você estiver usando o serviço de identidade do GKE pela primeira vez, poderá escolher entre configurar a compatibilidade com grupos de terceiros usando as APIs Fleet (recomendado) ou o kubectl.

Se você não for um usuário novo do GKE Identity Service, lembre-se de que:

• Se você já configurou o serviço de identidade do GKE para outro provedor de identidade no nível da frota, o recurso de grupos de terceiros estará ativado por padrão. Consulte a seção Frota abaixo para ver mais detalhes e outras configurações necessárias.

• Se você já tiver configurado o serviço de identidade do GKE para outro provedor de identidade por cluster, consulte a seção Kubectl abaixo para instruções sobre como atualizar sua configuração para recursos de grupos de terceiros.

Frota

Use o console do Google Cloud ou a linha de comando para configurar o acesso a grupos de terceiros usando as APIs Fleet Feature.

Console

Se você ainda não tiver configurado o GKE Identity Service para uma frota, siga as instruções em Configurar clusters para o GKE Identity Service.

Selecionar clusters e atualizar a configuração

1. No console do Google Cloud, acesse a página Gerenciador de recursos.

   Acessar o gerenciador de recursos

2. Clique em Detalhes no painel Serviço de identidade. Os detalhes do cluster do seu projeto são exibidos.

3. Clique em Atualizar serviço de identidade para abrir o painel de configuração.

4. Selecione os clusters que você quer configurar. É possível escolher clusters individuais ou especificar que todos os clusters sejam configurados com a mesma configuração de identidade.

5. Na seção Configurar provedores de identidade, você pode escolher reter, adicionar, atualizar ou remover um provedor de identidade.

6. Clique em Continuar para ir para a próxima etapa de configuração. Se você tiver selecionado pelo menos um cluster qualificado para essa configuração, a seção Autenticação do Google será exibida.

7. Selecione Ativar para habilitar a autenticação do Google para os clusters selecionados. Se você precisar acessar o provedor de identidade do Google usando um proxy, digite os detalhes do Proxy.

8. Clique em Atualizar configuração. Isso aplica a configuração de identidade nos clusters selecionados.

gcloud

Se você ainda não tiver configurado o GKE Identity Service para uma frota, siga as instruções em Configurar clusters para o GKE Identity Service. Especifique apenas a seguinte configuração no seu arquivo auth-config.yaml:

spec:
  authentication:
  - name: google-authentication-method
    google:
      disable: false

Como configurar o acesso a grupos de terceiros usando um proxy

Se você precisar acessar o provedor de identidade usando um proxy, use um campo proxy no seu arquivo auth-config.yaml. 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. É necessário adicionar essa configuração mesmo que você já tenha configurado o GKE Identity Service para outro provedor.

Para configurar o proxy, veja como atualizar a seção authentication do arquivo de configuração auth-config.yaml.

  spec:
    authentication:
    - name: authentication-method
      google:
        disable: false
      proxy: PROXY_URL

onde

• disable (opcional) indica se você quer ativar ou desativar o recurso de grupos de terceiros para clusters. Esse valor é definido como false por padrão. Se você quiser desativar esse recurso, defina-o como true.

• PROXY_URL (opcional) é o endereço do servidor proxy para se conectar à identidade do Google. Por exemplo: http://user:password@10.10.10.10:8888

Aplique a configuração

Para aplicar a configuração a um cluster, execute o seguinte comando:

gcloud container fleet identity-service apply \
--membership=CLUSTER_NAME \
--config=/path/to/auth-config.yaml

onde

CLUSTER_NAME é o nome de assinatura exclusivo do seu cluster na frota.

Depois de aplicada, essa configuração é gerenciada pelo controlador do GKE Identity Service. Todas as alterações locais feitas na configuração do cliente do GKE Identity Service serão reconciliadas de volta pelo controlador para a configuração especificada nesta configuração.

Kubectl

Para configurar o cluster para usar o serviço de identidade do GKE com o recurso de grupos de terceiros, é necessário atualizar o ClientConfig do serviço de identidade do GKE do cluster. Esse é um tipo de recurso personalizado (CRD, na sigla em inglês) do Kubernetes usado para a configuração do cluster. Cada cluster do GKE Enterprise tem um recurso ClientConfig chamado default no namespace kube-public que você atualiza com os detalhes da configuração.

Para editar a configuração, use o seguinte comando.

kubectl --kubeconfig CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

Se houver vários contextos no kubeconfig, o contexto atual será usado. Talvez seja necessário redefinir o contexto atual para o cluster correto antes de executar o comando.

Confira um exemplo de como atualizar o ClientConfig com um novo método de autenticação com uma configuração do tipo google para ativar o recurso de grupos de terceiros. Se o campo internalServer estiver vazio, verifique se ele está definido como https://kubernetes.default.svc, conforme mostrado abaixo.

spec:
  authentication:
  - google:
      audiences:
      - "CLUSTER_IDENTIFIER"
    name: google-authentication-method
    proxy: PROXY_URL
  internalServer: https://kubernetes.default.svc

onde

CLUSTER_IDENTIFIER (obrigatório) indica os detalhes de associação do cluster. Use o comando a seguir para recuperar os detalhes de associação do cluster:

kubectl --kubeconfig CLUSTER_KUBECONFIG get memberships membership -o yaml

onde

CLUSTER_KUBECONFIG é o caminho do arquivo kubeconfig do cluster. Na resposta, consulte o campo spec.owner.id para recuperar os detalhes da associação do cluster.

Veja a seguir um exemplo de resposta que mostra os detalhes de associação de um cluster:

id: //gkehub.googleapis.com/projects/123456789/locations/global/memberships/xy-ab12cd34ef

que corresponde ao seguinte formato: //gkehub.googleapis.com/projects/PROJECT_NUMBER/locations/global/memberships/MEMBERSHIP

Conceder papéis do IAM a usuários e grupos de terceiros

As identidades de terceiros precisam dos seguintes papéis adicionais do Google Cloud para interagir com clusters conectados pelo gateway:

• roles/gkehub.gatewayAdmin: esse papel permite que os usuários acessem a API do gateway do Connect.
  • Se os usuários só precisarem de acesso somente leitura aos clusters conectados, use roles/gkehub.gatewayReader.
  • Se os usuários precisarem de acesso de leitura/gravação aos clusters conectados, poderá usar roles/gkehub.gatewayEditor.
• roles/gkehub.viewer: esse papel permite que os usuários acessem as assinaturas registradas a clusters.

Confira a seguir como adicionar os papéis necessários a identidades individuais e grupos mapeados:

Identidades únicas

Para conceder os papéis necessários a uma única identidade para o projeto PROJECT_ID, execute o seguinte comando:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

onde

• PROJECT_ID é o ID do projeto.
• GATEWAY_ROLE é um dos campos roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader ou gkehub.gatewayEditor.
• WORKFORCE_POOL_ID é o ID do pool de identidade da força de trabalho.
• SUBJECT_VALUE é a identidade do usuário.

Grupos

Para conceder os papéis necessários a todas as identidades em um grupo específico para o projeto PROJECT_ID, execute o seguinte comando:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

onde

• PROJECT_ID é o ID do projeto.
• GATEWAY_ROLE é um dos campos roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader ou gkehub.gatewayEditor.
• WORKFORCE_POOL_ID: é o ID do pool da força de trabalho.
• GROUP_ID: é um grupo na declaração google.groups mapeada.

Consulte a configuração do seu provedor de identidade listada em Configurar mapeamentos de terceiros com a identidade da força de trabalho para mais personalizações, como especificar atributos do departamento, ao aplicar a política de RBAC.

Saiba mais sobre como conceder permissões e papéis do IAM em Como conceder, alterar e revogar acesso a recursos.

Configurar políticas de controle de acesso baseado em papéis (RBAC, na sigla em inglês)

Por fim, o servidor da API Kubernetes de cada cluster precisa autorizar comandos kubectl que passam pelo gateway do usuário e dos grupos de terceiros especificados. Para cada cluster, você precisa adicionar uma política de permissões do RBAC que especifica quais permissões o assunto tem no cluster.

Observação: o caminho do recurso de um usuário de terceiros não inclui o nome do provedor de identidade. Para evitar permissões inesperadas, verifique se você não está usando os mesmos nomes de usuário ou grupo em provedores de identidade diferentes para um único pool de força de trabalho.

Os assuntos nas políticas do RBAC precisam usar o mesmo formato das vinculações do IAM, com usuários de terceiros começando com principal://iam.googleapis.com/ e grupos de terceiros começando com principalSet://iam.googleapis.com/. Se o serviço de identidade do GKE não estiver configurado para o cluster, você precisará de políticas de representação, além de papéis/papéis de cluster para um usuário de terceiros. Nesse caso, siga estas etapas de configuração do RBAC, adicionando o principal de terceiros que começa com principal://iam.googleapis.com/ como usuário.

No exemplo a seguir, mostramos como conceder permissões cluster-admin aos membros de um grupo de terceiros em um cluster em que o serviço de identidade do GKE está configurado. Em seguida, salve o arquivo de política como /tmp/admin-permission.yaml e aplique-o ao cluster associado ao contexto atual.

cat <<EOF > /tmp/admin-permission.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gateway-cluster-admin-group
subjects:
- kind: Group
  name: "principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP"
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
EOF
# Apply permission policy to the cluster.
kubectl apply --kubeconfig=KUBECONFIG_PATH -f /tmp/admin-permission.yaml

Saiba mais sobre como especificar permissões de RBAC em Como usar a autorização RBAC.

Observação: Nossos exemplos mostram a aplicação de atualizações de políticas diretamente com kubectl. Para uso real, recomendamos o uso do Controlador de Políticas para criar e gerenciar políticas com o Config Sync para sincronizar essas políticas e outras configurações entre os clusters.

A seguir

• Saiba como usar o gateway do Connect para se conectar a clusters a partir da linha de comando.
• Veja um exemplo de como usar o gateway do Connect como parte da sua automação de DevOps no tutorial Como integrar com o Cloud Build.