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 Visualização. 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 (STS).

    Ative as APIs

  • 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, recomendamos que você faça isso em um ambiente de desenvolvimento ou teste.

  • Outras instruções específicas para o provedor

    SAML

    Se você planeja configurar a federação usando um provedor de identidade compatível com SAML 2.0, siga também as etapas abaixo.

    • Identifique qual projeto você usará ao configurar a federação de identidade da carga de trabalho.

    • Peça à equipe de conta do Google Cloud para solicitar acesso à visualização SAML 2.0 para seu projeto. Sua equipe de contas do Google Cloud notificará você quando tiver acesso à visualização.

    • Use a ferramenta gcloud para configurar a federação de identidade da carga de trabalho de um provedor de identidade SAML 2.0. Configure o billing/quota_project para o projeto que recebeu acesso à visualização SAML.

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.

    Em vez de definir um URI de ID de aplicativo personalizado, é possível usar o seguinte URI:

    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 URI do ID do aplicativo identifique um provedor de pools de Identidade da carga de trabalho de maneira exclusiva.

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.

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, aURI de metadados OIDC precisa ser acessível publicamente pela Internet e usar o endpoint ISSUER/.well-known/openid-configuration , em queISSUER é o URL do emissor que identifica exclusivamente seu provedor. 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.

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.

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, recomendamos que você faça isso 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 do EC2 específicas ou por papel.

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.

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

SAML

Os mapeamentos de atributos podem usar os elementos e 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'

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 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 um provedor compatível com OIDC, como o Microsoft Azure.
    • Não é possível configurar a federação de identidade da carga de trabalho de um provedor de identidade SAML 2.0 usando o Console do Cloud. Use a ferramenta 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, digite o seguinte:

  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"
    

    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:

    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"
    

    Se você receber o seguinte erro:

    INVALID_ARGUMENT: Invalid WorkloadIdentityPoolProvider IDP configuration: PROVIDERCONFIG_NOT_SET.
    

    Verifique se você concluiu as etapas descritas na página de solicitação de acesso de visualização SAML.

A seguir