Como configurar a federação de identidade da carga de trabalho

Neste guia, descrevemos como usar credenciais emitidas por um provedor de identidade externo para personificar uma conta de serviço e acessar recursos no Google Cloud. Esse processo é chamado de federação de identidades de carga de trabalho

Os casos de uso comuns da federação de identidade da carga de trabalho incluem:

  • Permitir um aplicativo em segundo plano ou um pipeline de integração/entrega contínua (CI/CD) executado fora do Google Cloud para acessar recursos e APIs do Google Cloud
  • Permitir que usuários de um aplicativo da Web executado fora do Google Cloud acessem dados armazenados em um serviço do Google Cloud, como o Cloud Storage ou o BigQuery

Para usar a federação de identidade da carga de trabalho, configure o Google Cloud para confiar em um provedor de identidade externo, como Amazon Web Services (AWS), Azure Active Directory (AD), um provedor de identidade compatível com OIDC ou um provedor de identidade compatível com SAML 2.0. Os aplicativos podem usar credenciais emitidas pelo provedor de identidade externo para personificar uma conta de serviço seguindo estas etapas:

  1. Consiga uma credencial do provedor de identidade confiável.
  2. Troque a credencial por um token do Security Token Service.
  3. Use o token do Security Token Service para personificar uma conta de serviço e receber um token de acesso de curta duração do Google.

Ao usar a federação de identidade da carga de trabalho, é possível evitar a necessidade de armazenar e gerenciar as chaves da conta de serviço.

Antes de começar

  • Ative as APIs IAM, Resource Manager, Service Account Credentials, and Security Token Service.

    Ative as APIs

Funções exigidas

Para receber as permissões necessárias para configurar a federação de identidade da carga de trabalho, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Administrador de pool de Identidade da carga de trabalho (roles/iam.workloadIdentityPoolAdmin)
  • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)

Para mais informações sobre como conceder papéis, consulte Gerenciar o acesso.

Como alternativa, o papel básico de Proprietário do IAM (roles/owner) também inclui permissões para configurar a federação de identidade. Não conceda papéis básicos em um ambiente de produção, recomendamos que você faça isso em um ambiente de desenvolvimento ou teste.

Como preparar o provedor de identidade externo

Para usar a federação de identidade da carga de trabalho, configure um pool de identidades de carga de trabalho e um provedor de pools de identidades de carga de trabalho no seu projeto.

AWS

Os usuários da AWS e os papéis da AWS podem usar uma credencial de segurança permanente ou temporária da AWS para personificar uma conta de serviço no Google Cloud.

Para permitir o uso de credenciais de segurança da AWS, configure o pool de identidade da carga de trabalho para confiar na sua conta da AWS. Os tokens de credenciais de segurança emitidos para essa conta da AWS são reconhecidos pela federação de identidade da carga de trabalho. É possível usar os tokens para receber credenciais de conta de serviço de curta duração.

Azure

Os usuários e principais de serviços do Azure podem usar tokens de acesso do Azure AD para personificar uma conta de serviço no Google Cloud.

Para permitir o uso de tokens de acesso do Azure AD, configure o pool de identidades da carga de trabalho para confiar em um aplicativo do Azure AD. Os tokens de acesso emitidos para esse aplicativo são reconhecidos pela federação de identidade da carga de trabalho. Use-os para receber credenciais de conta de serviço de curta duração.

Como prática recomendada, crie um novo aplicativo no Azure AD e use-o apenas para receber credenciais do Google Cloud:

  1. Crie um aplicativo do Azure AD e a entidade de serviço.

  2. Defina o URI do ID do aplicativo.

    Ao definir o URI do ID do aplicativo, o padrão será api://<appid>. Observe o URI, porque você precisará dele mais tarde ao criar o provedor do pool de identidades da carga de trabalho e o arquivo de configuração da credencial.

Você precisará do URI do ID do aplicativo mais tarde, quando configurar o provedor de pools de Identidade da carga de trabalho.

Para permitir que um aplicativo consiga tokens de acesso para o aplicativo Azure AD, use as identidades gerenciadas:

  1. Crie uma identidade gerenciada. Anote o ID do objeto da identidade gerenciada. Você precisará dele posteriormente ao configurar a representação.

  2. Atribua a identidade gerenciada a uma máquina virtual ou a outro recurso que execute o aplicativo.

Ações do GitHub

É possível permitir que um fluxo de trabalho de ações do GitHub use um token OIDC do GitHub para personificar uma conta de serviço no Google Cloud.

Para permitir o uso desses tokens, configure o pool de identidades da carga de trabalho para confiar nos tokens OIDC emitidos pelo GitHub. Os tokens de ID emitidos para os fluxos de trabalho são reconhecidos pela federação de identidade da carga de trabalho, e você pode usar os tokens para receber credenciais de conta de serviço de curta duração.

OIDC

É possível permitir que usuários e aplicativos personifiquem uma conta de serviço no Google Cloud usando tokens de ID ou acesso no formato JSON Web Token . token emitido por um provedor de identidade compatível com OIDC.

Para permitir o uso desses tokens, configure o pool de identidades da carga de trabalho para confiar no provedor de identidade externo. Os tokens emitidos pelo provedor de identidade externo são reconhecidos pela federação de identidade da carga de trabalho. É possível usar os tokens para receber credenciais de conta de serviço de curta duração.

Para usar a federação de identidade da carga de trabalho, o URI de metadados OIDC do provedor de identidade precisa ser acessível publicamente pela Internet e usar o endpoint ISSUER/.well-known/openid-configuration, em queISSUER é o valor da declaração de emissor (iss) no token. O Google consulta o endpoint de metadados para receber o conjunto de chaves da Web JSON (JWKS) do seu provedor e usa esse conjunto de chaves para validar os tokens.

Normalmente, é melhor usar tokens de ID ao realizar uma troca de tokens, porque eles refletem a identidade do usuário. Se decidir usar tokens de acesso, configure um aplicativo ou recurso dedicado no seu provedor de identidade com a única finalidade de receber credenciais do Google Cloud.

Por padrão, a federação de identidade da carga de trabalho espera tokens que usam o seguinte URL como declaração de público-alvo (aud):

https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

Substitua:

  • PROJECT_NUMBER: número do projeto do Google Cloud que você usa para criar o pool de identidades da carga de trabalho;
  • POOL_ID: ID de sua escolha que identifica o pool de identidades da carga de trabalho. É necessário usar o mesmo ID ao criar o pool de identidades da carga de trabalho posteriormente.
  • PROVIDER_ID: ID de sua escolha que identifica o provedor de pools de identidades de cargas de trabalho. É necessário usar o mesmo ID ao criar o provedor do pool de identidades de carga de trabalho posteriormente.

É possível especificar uma lista personalizada de públicos-alvo permitidos ao criar o pool de identidades e o provedor de carga de trabalho.

OIDC (AD FS)

Os usuários do Active Directory podem usar tokens de acesso do OIDC dos Serviços de federação do Active Directory (AD FS, na sigla em inglês) para personificar uma conta de serviço no Google Cloud.

Para permitir que um aplicativo solicite tokens de acesso do AD FS e use esses tokens para acessar o Google Cloud, você precisa de dois registros de aplicativos no AD FS:

  1. Um registro de aplicativo do tipo aplicativo nativo ou aplicativo de servidor.

  2. Um registro de aplicativo do tipo API da Web que corresponda a um provedor de pool de identidades da carga de trabalho no Google Cloud.

Em seguida, configure um provedor de identidades da carga de trabalho para aceitar tokens de acesso emitidos para a API da Web.

Como usar a Autenticação integrada do Windows

É possível combinar a federação de identidade da carga de trabalho com a Autenticação integrada do Windows (IWA). A IWA permite que os aplicativos do Active Directory façam autenticação no AD FS usando credenciais do Kerberos ou NTLM. Ao combinar a federação de identidade da carga de trabalho e a IWA, você evita armazenar e gerenciar credenciais de clientes e chaves da conta de serviço do AD FS.

Para usar a IWA, verifique se estes requisitos foram atendidos:

Como registrar o aplicativo cliente

Para registrar um aplicativo no AD FS para o Windows Server 2019, faça o seguinte:

  1. Abra o snap-in de MMC do AD FS e acesse Grupos de aplicativos.
  2. Clique em Adicionar grupo de aplicativos.
  3. Na página de Boas-vindas, insira um nome para o cliente e selecione aplicativo de servidor. Depois, clique em Avançar.
  4. Na página do aplicativo de servidor, insira um identificador de cliente (ID do cliente) e um URI de redirecionamento. Se você vai usar apenas o tipo de concessão client_credentials, o URI de redirecionamento não será usado, e é possível usar um URI como http://localhost/. Depois, clique em Avançar.
  5. Na página de configuração de credenciais do aplicativo, escolha como o cliente vai ser autenticado. Para usar a IWA, defina a Autenticação integrada do Windows como ativada e selecione o usuário do domínio em que seu aplicativo está configurado para ser executado. Depois, clique em Avançar.
  6. Na página Resumo, revise as configurações e clique em Avançar.
  7. Clique em Fechar para dispensar a caixa de diálogo.

Como criar um aplicativo de API da Web para o pool de federação de identidade da carga de trabalho

Crie outro registro de aplicativo do tipo API da Web. Esse aplicativo corresponde a um provedor de pool de identidades da carga de trabalho, que pode ser usado para configurar uma relação de confiança com o Google Cloud.

Para criar o aplicativo no AD FS para o Windows Server 2019, faça o seguinte:

  1. Abra o snap-in de MMC do AD FS e acesse Grupos de aplicativos.
  2. Clique em Adicionar grupo de aplicativos.
  3. Na página de Boas-vindas, insira um nome como Workload Identity Federation (test environment) e selecione API da Web. Depois, clique em Avançar.

  4. Na página Configurar API da Web, insira um identificador da parte confiável para essa API.

    Em vez de personalizar um identificador da parte confiável, use o seguinte URI como identificador da parte confiável:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    Substitua os seguintes valores:

    • PROJECT_NUMBER: número do projeto do Google Cloud que você usa para criar o pool de identidades da carga de trabalho.
    • POOL_ID: ID de sua escolha que identifica o pool de identidades da carga de trabalho. É necessário usar o mesmo ID ao criar o pool de identidades da carga de trabalho posteriormente.
    • PROVIDER_ID: ID de sua escolha que identifica o provedor de pools de Identidades de cargas de trabalho; É necessário usar o mesmo ID ao criar o provedor do pool de identidades de carga de trabalho posteriormente.

    Esse formato garante que o identificador da parte confiável identifique exclusivamente um provedor de pool de identidades da carga de trabalho.

    Você vai precisar do identificador da parte confiável mais adiante ao configurar o provedor de pool de identidades da carga de trabalho.

  5. Clique em Próxima.

  6. Na página Aplicar política de controle de acesso, selecione uma política de acesso apropriada e clique em Avançar.

  7. Na página Configurar permissões do aplicativo, adicione o aplicativo cliente que você criou. Depois clique em Next.

  8. Na página Resumo, revise as configurações e clique em Avançar.

  9. Clique em Fechar para dispensar a caixa de diálogo.

SAML

É possível permitir que usuários e aplicativos personifiquem uma conta de serviço no Google Cloud usando declarações emitidas por um provedor de identidade compatível com SAML 2.0. A federação que usa declarações criptografadas não é compatível.

Configure seu provedor de identidade SAML para emitir declarações com o provedor de pools de identidades de carga de trabalho como público-alvo no formato https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.

Para permitir o uso dessas declarações, configure o pool de identidades da carga de trabalho para confiar no seu provedor de identidade externo, fornecendo o documento de metadados do seu provedor de identidade SAML.

A federação de identidade da carga de trabalho reconhece as declarações emitidas pelo provedor de identidade externo e é possível usar os tokens para receber credenciais de conta de serviço de curta duração.

SAML (AD FS)

É possível permitir que aplicativos representem uma conta de serviço no Google Cloud usando uma declaração SAML 2.0 pelo Active Directory Federation Services (AD FS).

Para permitir que os aplicativos solicitem uma declaração SAML do AD FS que possa ser usada para a federação de identidade da carga de trabalho, você precisa criar uma relação de confiança com terceira parte confiável. Para criar uma relação de confiança com terceira parte confiável no AD FS para o Windows Server 2019:

  1. Abra o snap-in do MMC do AD FS e navegue até Relação de confiança com terceira parte confiável.
  2. Clique em Adicionar relação de confiança com terceira parte confiável.
  3. Na página de Boas-vindas do assistente Adicionar relação de confiança com terceira parte confiável, selecione Claimsaware e clique em Iniciar.
  4. Na página Selecionar a fonte de dados selecioneInserir dados sobre a terceira parte confiável manualmente. Depois, clique em Avançar.
  5. Na página Especificar nome de exibição, digite um nome para a relação de confiança. Depois clique em Next.
  6. Na página Configurar certificado, clique em Avançar. Não é necessário um certificado de criptografia porque a federação de identidade da carga de trabalho não suporta declarações SAML criptografadas.
  7. Na página Configurar URL, mantenha as configurações padrão e clique em Avançar.

  8. Na página Configurar identificadores, insira um identificador de terceira parte confiável.

    Em vez de personalizar um identificador da parte confiável, use o seguinte URI como identificador da parte confiável:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    Substitua:

    • PROJECT_NUMBER: número do projeto do Google Cloud que você usa para criar o pool de identidades da carga de trabalho.
    • POOL_ID: ID de sua escolha que identifica o pool de identidades da carga de trabalho. É necessário usar o mesmo ID ao criar o pool de identidades da carga de trabalho posteriormente.
    • PROVIDER_ID: ID de sua escolha que identifica o provedor de pools de Identidades de cargas de trabalho; É necessário usar o mesmo ID ao criar o provedor do pool de identidades de carga de trabalho posteriormente.

    Esse formato garante que o identificador da parte confiável identifique exclusivamente um provedor de pool de identidades da carga de trabalho.

    Você vai precisar do identificador da parte confiável mais adiante ao configurar o provedor de pool de identidades da carga de trabalho.

  9. Clique em Próxima.

  10. Na página Escolher política de controle de acesso, selecione uma política de controle de acesso apropriada e clique em Avançar.

  11. Na página Ready to add trust, revise as configurações e clique em Avançar.

  12. Na página Concluir, clique em Fechar para dispensar a caixa de diálogo.

Para serem compatíveis com a federação de identidade da carga de trabalho, as declarações SAML precisam conter pelo menos uma reivindicação que identifique o usuário do Active Directory de maneira exclusiva. Normalmente, usa-se a reivindicação ID de nome para essa finalidade, que corresponde ao valor do elemento NameID na declaração SAML.

Para personalizar o conjunto de declarações da asserção SAML, é necessário editar a política de emissão de reivindicações da relação de confiança com terceira parte confiável. Para editar a política de emissão de reivindicações, faça o seguinte:

  1. Na lista de relações de confiança com terceira parte confiável, selecione a confiança que você acabou de criar e clique em Editar política de emissão de declarações.
  2. Clique em Adicionar regra.
  3. Na página Escolher tipo de regra do assistente Adicionar regra de reivindicação de transformação, selecione Transformar uma reivindicação de entrada. Depois, clique em Avançar.

  4. Na página Configurar regra de declaração, defina as seguintes configurações:

    • Nome da regra de reivindicação: Name Identifier.
    • Tipo de reivindicação de entrada: selecione SID principal, UPN ou outra reivindicação para identificar o sujeito de forma exclusiva.
    • Tipo de reivindicação de saída: ID de nome.
    • Formato de ID de nome de saída: Não especificado.

  5. Selecione Passar por todos os valores de reivindicação e clique em Concluir.

  6. Você também pode configurar regras adicionais para incluir mais atributos nas declarações SAML.

  7. Clique em OK para fechar a caixa de diálogo da política de emissão de reivindicações.

Como configurar a federação

Para fazer a federação com o provedor de identidade externo, faça o seguinte:

  1. Prepare um projeto do Google Cloud que contenha o pool de identidades e o provedor da carga de trabalho.
  2. Defina um mapeamento de atributo e uma condição opcional que mapeie as credenciais do provedor de identidade para identidades externas.
  3. Crie um pool de identidades e um provedor de carga de trabalho

As seções a seguir orientam você nesse processo.

Preparar o projeto

Selecione e prepare o projeto que conterá o pool de identidades e o provedor da carga de trabalho:

  1. Verifique se você tem os papéis Administrador de pool de Identidade da carga de trabalho (roles/iam.workloadIdentityPoolAdmin) e Administrador da conta de serviço (roles/iam.serviceAccountAdmin) no projeto.

    Como alternativa, o papel básico de Proprietário do IAM (roles/owner) também inclui permissões para configurar a federação de identidade. Não conceda papéis básicos em um ambiente de produção. No entanto, é possível concedê-los em um ambiente de desenvolvimento ou teste.

  2. Atualize a política da organização para permitir a federação.

  3. Ative as APIs IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS).

    Ative as APIs

Definir um mapeamento e uma condição de atributo

Defina um mapeamento de atributo e uma condição opcional que mapeie as credenciais do provedor de identidade para identidades externas.

As credenciais emitidas pelo provedor de identidade externo contêm um ou mais atributos, também chamados de declarações. A federação de identidade da carga de trabalho se refere a esses atributos como atributos de declaração e utiliza prefixos com assertion. neles.

Um mapeamento de atributos permite mapear os atributos de declaração para os atributos de destino predefinidos reconhecidos pela federação de identidade da carga de trabalho. Estes atributos predefinidos de destino são:

Atributo Descrição
google.subject Obrigatório. Um identificador exclusivo do usuário. Esse atributo é usado nas vinculações de papéis principal:// do IAM e aparece nos registros do Cloud Logging. O valor precisa ser exclusivo e não pode exceder 127 caracteres.
google.groups Opcional. Um conjunto de grupos ao qual a identidade pertence. Esse atributo é usado nas vinculações de papéis principalSet:// do IAM para conceder acesso a todos os membros de um grupo.
attribute.NAME Opcional. É possível definir até 50 atributos personalizados e usar esses atributos nas vinculações de papéis principalSet:// do IAM para conceder acesso a todas as identidades com um determinado atributo.

Um mapeamento de atributo tem o formato TARGET_ATTRIBUTE=SOURCE_EXPRESSION. Veja os exemplos a seguir:

  • Esse mapeamento atribui o atributo sub da declaração a google.subject:

    google.subject=assertion.sub

  • Esse mapeamento usa uma expressão de Common Expression Language (CEL) para concatenar vários atributos de declaração:

    google.subject="myprovider::" + assertion.aud + "::" + assertion.sub

  • Esse mapeamento usa outra expressão CEL para mapear um atributo de declaração com valor de GUID workload_id para um nome e atribui o resultado a um atributo personalizado chamado attribute.my_display_name:

    attribute.my_display_name={
  "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1",
  "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2"
}[assertion.workload_id]

  • Esse mapeamento usa operadores e funções lógicos CEL para definir um atributo personalizado chamado attribute.environment como prod ou test, dependendo do Nome do Recurso da Amazon da identidade (RAN):

    attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"

  • Esse mapeamento usa a função extract para preencher um atributo personalizado aws_role com o nome do papel presumido ou, se nenhum papel tiver sido presumido, com o da identidade ARN

    attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

Também é possível definir uma condição de atributo. As condições do atributo são expressões CEL que podem verificar atributos de declaração e atributos de destino. Se a condição do atributo for avaliada como true para uma determinada credencial, a credencial será aceita. Caso contrário, a credencial será rejeitada.

Para escolher os mapeamentos e condições de atributos certos para seu caso de uso, você precisa decidir se mapear as identidades de serviço ou as identidades de usuários:

  • Ao mapear as identidades de serviço, é possível ativar um aplicativo em segundo plano ou um pipeline de CI/CD que seja executado fora do Google Cloud para receber credenciais de curta duração para o Google Cloud. O aplicativo recebe essas credenciais de curta duração em seu próprio nome, sem o envolvimento do usuário.
  • Ao mapear as identidades dos usuários, é possível permitir que os usuários de um aplicativo executado fora do Google Cloud recebam credenciais de curta duração para o Google Cloud. O aplicativo recebe essas credenciais de curta duração em nome do usuário.

Como mapear identidades de serviço

AWS

Os mapeamentos de atributos podem usar os campos de resposta para GetCallerIdentity como atributos de origem. Esses campos incluem:

  • account, que contém o número da conta da AWS.
  • arn, contendo o ARN da AWS da entidade externa.
  • userid, contendo o identificador exclusivo da entidade autora de chamadas.

Se o aplicativo for executado em uma instância do Amazon Elastic Compute Cloud (EC2) com um papel anexado, use o seguinte mapeamento de atributo:

google.subject=assertion.arn
attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

Esse mapeamento permite conceder a capacidade de personificar uma conta de serviço para instâncias específicas do EC2 ou por papel usando os seguintes identificadores:

Conceda acesso a uma instância específica do EC2: 

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE/AWS_ROLE_SESSION_NAME

Conceda acesso por papel: 

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE

Sua conta da AWS pode conter um grande número de usuários e papéis, mas apenas um pequeno subconjunto deles pode exigir acesso a recursos do Google Cloud. Para limitar o conjunto de usuários e papéis que podem usar a federação de identidade da carga de trabalho, use uma condição de atributo. Por exemplo, a condição a seguir permite que uma conta específica acesse recursos do Google Cloud:

assertion.arn.startsWith('arn:aws:sts::ACCOUNT-ID:assumed-role/')

Azure

Os mapeamentos de atributos podem usar as declarações incorporadas aos tokens de acesso do Azure, incluindo declarações personalizadas, como atributos de origem.

Para ver uma lista completa das declarações que você pode referenciar, conecte-se a uma VM do Azure que tenha uma identidade gerenciada atribuída e faça o seguinte:

  1. Consiga um token de acesso do Serviço de metadados de instância do Azure (IMDS):

    Bash

    curl \
  "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
  -H "Metadata: true" | jq -r .access_token

    Esse comando usa a ferramenta jq. jq está disponível por padrão no Cloud Shell.

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
$SubjectToken = (Invoke-RestMethod `
  -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
  -Headers @{Metadata="true"}).access_token
Write-Host $SubjectToken

    Substitua APP_ID_URI pelo URI do ID do aplicativo que você configurou para a federação de identidade da carga de trabalho.

  2. Em um navegador da Web, acesse https://jwt.ms/ e cole o token de acesso na caixa de texto.

  3. Clique em Reivindicações para ver a lista de reivindicações incorporadas no token de acesso.

Para autenticar com um principal de serviço, use o seguinte mapeamento de atributos:

google.subject=assertion.sub

Para um token de acesso emitido para uma identidade gerenciada, a declaração sub contém o ID do objeto da identidade gerenciada. Se você usar uma declaração diferente, verifique se ela é exclusiva e não pode ser reatribuída.

Para identidades de serviço, geralmente não é necessário criar um mapeamento para google.groups ou qualquer atributo personalizado.

Para controlar quais identidades podem receber credenciais de curta duração para o Google Cloud, não defina condições de atributos. Em vez disso, configure o aplicativo Azure AD para usar atribuições de papel de app.

Ações do GitHub

Os mapeamentos de atributos podem usar as declarações incorporadas no token OIDC como atributos de origem. São elas:

  • sub: contém o nome do repositório e a referência do Git, por exemplo, repo:username/reponame:ref:refs/heads/master.
  • repository: contém o nome do proprietário e do repositório, por exemplo, username/reponame.
  • repository_owner: contém o proprietário, que pode ser um nome de usuário ou o nome de uma organização do GitHub.
  • ref: contém a referência do Git, por exemplo, refs/heads/main.

O mapeamento de atributos a seguir define google.subject na declaração sub do token OIDC do GitHub Actions. Como a declaração sub contém o nome do repositório e a referência do Git, esse mapeamento permite controlar o acesso por repositório e ramificação:

google.subject=assertion.sub

O controle de acesso por repositório e branch pode ser útil se determinados branches (por exemplo, main) precisarem de acesso diferente aos recursos de outros branches, por exemplo, branches de recursos.

Se você não planeja diferenciar o acesso por branch, use o mapeamento de atributo a seguir, que define google.subject como a declaração repository:

google.subject=assertion.repository

Opcionalmente, é possível usar uma condição de atributo para definir requisitos adicionais que os tokens de ID precisem atender. Por exemplo, a condição a seguir limita o acesso a tokens de ID para fluxos de trabalho que usam a ramificação Git main:

assertion.ref=='refs/heads/main'

OIDC

Os mapeamentos de atributos podem usar as declarações incorporadas no token de ID ou de acesso emitido pelo provedor de identidade externo.

Mapeie uma dessas declarações para google.subject para identificar exclusivamente o usuário. Para se proteger contra ameaças de spoofing, escolha uma reivindicação com um valor exclusivo que não possa ser alterado.

Muitos provedores de identidade preenchem a declaração sub com um ID exclusivo e imutável. Para esses provedores de identidade, considere mapear a declaração sub para google.subject:

google.subject=assertion.sub

Evite usar uma reivindicação como email para essa finalidade. Geralmente, os endereços de e-mail podem ser reatribuídos ou alterados para que não identifiquem um usuário de maneira exclusiva e permanente.

Seu provedor de identidade pode conter um grande número de usuários, mas apenas um pequeno subconjunto deles pode exigir acesso a recursos do Google Cloud. Para limitar o conjunto de usuários e credenciais que podem usar a federação de identidade da carga de trabalho, é possível usar uma condição de atributo.

Por exemplo, a condição a seguir restringe o acesso a tokens que contêm uma declaração service_account personalizada com um valor true:

assertion.service_account==true

OIDC (AD FS)

Os mapeamentos de atributos podem usar as declarações incorporadas aos tokens de acesso do AD FS como atributos de origem.

Para autenticar um aplicativo, use o seguinte mapeamento de atributos:

google.subject=assertion.appid

Esse mapeamento define google.subject como o valor da declaração appid, que contém o ID do cliente do aplicativo do AD FS.

Outra opção é usar uma condição de atributo para definir requisitos adicionais que os tokens de acesso do AD FS precisam atender. Por exemplo, a condição a seguir define que os aplicativos precisam usar IWA para fazer autenticação no AD FS:

assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'

Para controlar a lista de aplicativos que podem conseguir credenciais de curta duração para o Google Cloud, não defina condições de atributos. Em vez disso, use permissões de cliente no AD FS para definir quais aplicativos são permitidos.

SAML

Os mapeamentos de atributos podem usar os elementos <Subject> e <Attribute> incorporados à declaração emitida pelo provedor de identidade externo. Os atributos SAML podem ser referenciados usando as seguintes palavras-chave:

  • assertion.subject contém o NameID do usuário autenticado encontrado no elemento <Subject>.
  • assertion.attributes['ATTRIBUTE_NAME'] contém uma lista de valores com o nome <Attribute>.

Mapeie uma dessas declarações para google.subject para identificar exclusivamente o usuário. Para se proteger contra ameaças de spoofing, escolha uma reivindicação com um valor exclusivo que não possa ser alterado.

Muitos provedores de identidade preenchem a NameId com um ID exclusivo e imutável. Para esses provedores de identidade, considere mapear o atributo NameId para google.subject:

google.subject=assertion.subject

Evite usar um atributo como http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress para essa finalidade. Geralmente, os endereços de e-mail podem ser reatribuídos ou alterados para que não identifiquem um usuário de maneira exclusiva e permanente.

Seu provedor de identidade pode conter um grande número de usuários, mas apenas um pequeno subconjunto deles pode exigir acesso a recursos do Google Cloud. Para limitar o conjunto de usuários e credenciais que podem usar a federação de identidade da carga de trabalho, é possível usar uma condição de atributo.

Por exemplo, a condição a seguir restringe o acesso a declarações que contenham um atributo https://example.com/SAML/Attributes/AllowGcpFederation personalizado com um valor true:

assertion.attributes['https://idp.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

SAML (AD FS)

Os mapeamentos de atributos podem usar as reivindicações incorporadas na declaração emitida pelo AD FS, conforme descrito anteriormente neste guia.

Use o seguinte mapeamento para permitir que a federação de identidade da carga de trabalho use a reivindicação ID de nome pela declaração SAML para identificar o usuário de forma exclusiva:

google.subject=assertion.subject

Se você configurou a política de emissão de reivindicação para incluir declarações adicionais em declarações SAML, será possível adicionar outros mapeamentos. Exemplo:

google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid']
attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]

Também é possível usar uma condição de atributo a que todas as declarações SAML precisam atender. Por exemplo, a condição a seguir permite apenas declarações SAML que incluam uma determinada reivindicação de associação a grupo:

"S-1-5-6" in google.groups

Crie um pool de identidades e um provedor de carga de trabalho

Coletamos todas as informações necessárias para criar um pool de identidades e um provedor de carga de trabalho:

Console

  1. No Console do Google Cloud, acesse a página Novo provedor de carga de trabalho e pool.

    Acessar "Novo provedor de carga de trabalho" e "Pool"

  2. Em Criar um pool de identidades, digite o seguinte:

    • Nome: o nome do pool. O nome também é usado como o ID do pool. Não será possível alterar o ID do pool posteriormente.
    • Descrição: texto que descreve a finalidade do pool.

  3. Clique em Continuar.

  4. Na lista suspensa Selecionar um provedor, escolha seu provedor:

    • AWS se você estiver federando com o AWS.
    • OpenID Connect (OIDC) se estiver federando com o Azure, o GitHub Actions ou outro provedor compatível com OIDC.
    • Não é possível configurar a federação de identidade da carga de trabalho em um provedor de identidade SAML 2.0 usando o Console do Google Cloud. Use a CLI gcloud para configurar a federação de identidade da carga de trabalho de um provedor de identidade SAML 2.0.

  5. Em Detalhes do provedor, insira os detalhes do seu provedor de identidade:

    AWS

    • Nome do provedor: nome do provedor. O nome também é usado como o ID do provedor. Não será possível alterar o ID depois.

    Azure

    • Nome do provedor: nome do provedor. O nome também é usado como o ID do provedor. Não será possível alterar o ID depois.
    • URL do emissor: https://sts.windows.net/TENANT_ID, em que TENANT_ID é o ID do locatário (GUID, na sigla em inglês) do locatário do Azure AD.
    • Públicos-alvo permitidos: o URI do ID do aplicativo que você usou quando registrou o aplicativo no Azure AD.

    Ações do GitHub

    • Nome do provedor: nome do provedor. O nome também é usado como o ID do provedor. Não será possível alterar o ID depois.
    • URL do emissor: https://token.actions.githubusercontent.com/

    OIDC

    • Nome do provedor: nome do provedor. O nome também é usado como o ID do provedor. Não será possível alterar o ID depois.
    • URL do emissor: URL do emissor do provedor de identidade.
    • Públicos-alvo permitidos: público-alvo esperado dos tokens de ID.

    OIDC (AD FS)

    • Nome do provedor: nome do provedor. O nome também é usado como o ID do provedor. Não será possível alterar o ID depois.
    • URL do emissor: https://ADFS_DOMAIN/adfs, em que ADFS_DOMAIN é o nome do domínio público do servidor ou farm do AD FS.

  6. Clique em Continuar.

  7. Em Configurar atributos do provedor, adicione os mapeamentos de atributos identificados anteriormente.

  8. Em Condições de atributo, digite a condição do atributo que você identificou anteriormente. Deixe o campo em branco se não houver uma condição de atributo.

  9. Clique em Salvar para criar o pool de identidades e o provedor da carga de trabalho.

gcloud

  1. Crie um novo pool de identidades de carga de trabalho:

    gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"

    Substitua os seguintes valores:

    • POOL_ID: o ID exclusivo do pool.
    • DISPLAY_NAME: nome do pool.
    • DESCRIPTION: descrição do pool; Essa descrição aparece ao conceder acesso às identidades do pool.

  2. Adicione um provedor de pool de identidades de carga de trabalho:

    AWS 

    gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
  --location="global"  \
  --workload-identity-pool="POOL_ID" \
  --account-id="AWS_ACCOUNT_ID" \
  --attribute-mapping="MAPPINGS" \
  --attribute-condition="CONDITIONS"

    Substitua os seguintes valores:

    Exemplo:

    gcloud iam workload-identity-pools providers create-aws example-provider \
  --location="global"  \
  --workload-identity-pool="pool-1" \
  --account-id="123456789000" \
  --attribute-mapping="google.subject=assertion.arn"

    Azure 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://sts.windows.net/TENANT_ID" \
    --allowed-audiences="APPLICATION_ID_URI" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua os seguintes valores:

    Exemplo:

    gcloud iam workload-identity-pools providers create-oidc example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --issuer-uri="https://sts.windows.net/00000000-1111-2222-3333-444444444444" \
    --allowed-audiences="api://my-app" \
    --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups"

    Ações do GitHub 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://token.actions.githubusercontent.com/" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua os seguintes valores:

    OIDC 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --allowed-audiences="AUDIENCE" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua os seguintes valores:

    OIDC (AD FS) 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://ADFS_DOMAIN/adfs" \
    --allowed-audiences="RELYING_PARTY_ID" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua os seguintes valores:

    SAML 

    gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --idp-metadata-path="IDP_METADATA_PATH" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua os seguintes valores:

    Exemplo:

    gcloud iam workload-identity-pools providers create-saml example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --idp-metadata-path="/path/to/idp_metadata.xml" \
    --attribute-mapping="google.subject=assertion.subject,google.groups=assertion.attributes.groups"

    SAML (AD FS) 

    curl -O https://DOMAIN/federationmetadata/2007-06/federationmetadata.xml

gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --idp-metadata-path="federationmetadata.xml" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua:

    Exemplo:

    gcloud iam workload-identity-pools providers create-saml example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --idp-metadata-path="federationmetadata.xml" \
    --attribute-mapping=google.subject=assertion.subject"

A seguir