Configurar a federação de identidade da carga de trabalho com o Active Directory

Neste guia, descrevemos como usar a federação de identidade da carga de trabalho para permitir que as cargas de trabalho usem credenciais do Active Directory para autenticação no Google Cloud.

Se você estiver executando cargas de trabalho do Windows Server em um ambiente do Active Directory, essas cargas de trabalho poderão ter acesso a credenciais do Active Directory. Por exemplo:

  • Um Serviço do Windows pode ser configurado para fazer login como um usuário do domínio.
  • Um aplicativo IIS pode ser configurado para ser executado como uma conta de serviço gerenciada para o grupo (gMSA).

Ao usar a federação de identidade da carga de trabalho em combinação com o Active Directory Federation Services (AD FS), é possível permitir que essas cargas de trabalho troquem as credenciais do Active Directory Kerberos por credenciais de curta duração do Google Cloud. As cargas de trabalho podem usar essas credenciais de curta duração para acessar as APIs do Google Cloud.

A troca de credenciais do Active Directory por credenciais de curta duração do Google Cloud encadeia duas trocas de token:

  1. Uma carga de trabalho usa o OpenID Connect (OIDC), SAML-POST ou WS-Trust para solicitar um token OIDC ou declaração SAML do AD FS. Para autenticar no AD FS, a carga de trabalho usa a autenticação integrada do Windows (IWA) e as credenciais atuais do Active Directory.
  2. Em seguida, a carga de trabalho usa a federação de identidade da carga de trabalho para trocar o token OIDC ou declaração SAML por um token do Security Token Service e, opcionalmente, representar uma conta de serviço do Google Cloud.

Neste documento, mostramos como automatizar esse processo de forma que não exija alterações no seu aplicativo usando o Workload Authenticator para Windows.

Preparar o AD FS

Você só precisa realizar essas etapas uma vez.

Selecionar um protocolo

A maneira de preparar o AD FS depende do protocolo que você quer usar:

  • SAML: é possível permitir que as cargas de trabalho usem SAML ou WS-Trust para receber declarações SAML.

    Para usar o SAML ou o WS-Trust, crie uma parte confiável no AD FS e configure um pool de identidades de carga de trabalho para confiar em declarações emitidas para essa parte confiável.

    Uma carga de trabalho pode usar o usuário do Active Directory para se autenticar no AD FS, seja usando a vinculação SAML-POST ou o WS-Trust. Em seguida, o AD FS emite uma declaração SAML que contém informações sobre o usuário do Active Directory da carga de trabalho e outras informações, como associações ao grupo.

    O uso de SAML ou WS-Trust requer o AD FS 3.0, o AD FS para o Windows Server 2016 ou uma versão mais recente do AD FS.

  • OIDC: é possível permitir que cargas de trabalho usem o OIDC para receber tokens do OIDC.

    Para usá-lo, crie um cliente OIDC (aplicativo nativo) e um recurso OIDC (API Web) no AD FS. Em seguida, configure um pool de identidades de carga de trabalho para confiar em tokens de acesso emitidos para a API Web.

    Uma carga de trabalho pode usar o usuário do Active Directory e a concessão de client_credentials do OAuth para autenticação no AD FS. Em seguida, o AD FS emite um token de acesso, mas não um token de ID.

    O token de acesso contém informações sobre o aplicativo cliente OIDC, mas não inclui informações sobre o usuário do Active Directory da carga de trabalho nem as associações ao grupo.

    Como os tokens de acesso não contêm informações sobre o usuário do Active Directory, usar OIDC pode ser menos flexível do que usar SAML ou WS-Trust.

    O uso do OIDC requer o AD FS para o Windows Server 2016 ou uma versão mais recente do AD FS.

Para fazer login, seu IdP precisa fornecer informações de autenticação assinadas. Os IdPs OIDC precisam fornecer um JWT, e as respostas do IdP SAML precisam ser assinadas.

Pré-requisitos do IWA

Nesta seção, descrevemos os pré-requisitos do IWA necessários para usar este guia.

Se você nunca usou o IWA com o AD FS, verifique se atende aos seguintes pré-requisitos:

Registrar a carga de trabalho

Para registrar a carga de trabalho no AD FS, faça o seguinte:

OIDC

Para permitir que as cargas de trabalho usem o OIDC, você precisa de dois registros de aplicativos no AD FS:

  • Um registro de aplicativo do tipo app nativo ou aplicativo de servidor.

  • 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.

Como registrar o aplicativo cliente

Crie um aplicativo cliente que represente a carga de trabalho. Se você tiver várias cargas de trabalho que precisam de acesso ao Google Cloud, talvez seja necessário criar vários aplicativos cliente.

Para registrar um aplicativo cliente no AD FS, siga estas etapas:

  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, faça o seguinte:

    1. No campo de texto, insira um nome para o cliente.
    2. Selecione Aplicativo do servidor.
    3. Clique em Próxima.

  4. Na página Aplicativo do servidor, faça o seguinte:

    1. No campo de texto text-field, 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/.

    2. Clique em Próxima.

  5. Na página Configurar credenciais do aplicativo, faça o seguinte:

    1. Escolha como o cliente fará a autenticação. Para usar a IWA, defina a Autenticação Integrada do Windows como ativada.
    2. Selecione o usuário do domínio em que o aplicativo está configurado para ser executado.
    3. Clique em Próxima.

  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 identidade da carga de trabalho

Crie outro registro de aplicativo do tipo API da Web. Esse aplicativo corresponde a um provedor de pool de identidade 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, siga estas etapas:

  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 definir um identificador personalizado, use o seguinte URI como identificador da parte confiável:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_POOL_ID/providers/WORKLOAD_PROVIDER_ID

    Substitua:

    • PROJECT_NUMBER: o número do projeto do Google Cloud que você usa para criar o pool de identidade da carga de trabalho.
    • WORKLOAD_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.
    • WORKLOAD_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 de pool de identidade da carga de trabalho posteriormente.

    A formatação do URI dessa maneira garante que o identificador da parte confiável identifique exclusivamente um provedor de pool de identidade da carga de trabalho.

    Você precisará do identificador da parte confiável mais adiante ao configurar o provedor de pool de identidade 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 ou confiança WS

Crie uma relação de confiança com parte confiável no AD FS:

  1. Abra o snap-in do MMC do AD FS.
  2. Acesse Relações confiáveis de terceiros.
  3. Clique em Adicionar relação de confiança com terceira parte confiável.
  4. Na página de boas-vindas do assistente Adicionar relação de confiança com a parte confiável, faça o seguinte:
    1. Selecione Reconhecimento de reivindicações.
    2. Clique em Iniciar.
  5. Na página Selecionar fonte de dados, faça o seguinte:
    1. Selecione Inserir dados sobre terceiros confiáveis manualmente.
    2. Clique em Próxima.

  6. Na página Especificar nome de exibição, faça o seguinte:

    1. Digite um nome para a confiança.
    2. Clique em Próxima.

  7. Na página Configurar certificado, clique em Avançar. Embora a federação de identidade da carga de trabalho seja compatível com SAML criptografado, não a descrevemos neste procedimento. Para saber mais, consulte as instruções da CLI gcloud em Criar o pool de identidades e o provedor, mais adiante neste guia.

  8. Na página Configurar URL, faça o seguinte:

    SAML

    Use as seguintes configurações:

    • Defina Ativar suporte para o protocolo WebSSO do SAML 2.0 como ativado.

    • No campo URL de serviço de SSO do SAML 2.0 da parte confiável, digite o seguinte URL:

      https://sts.googleapis.com/v1/token

    Confiança WS

    Mantenha as configurações padrão

  9. Clique em Próxima.

  10. 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/WORKLOAD_POOL_ID/providers/WORKLOAD_PROVIDER_ID

    Substitua:

    • PROJECT_NUMBER: o número do projeto do Google Cloud que você usa para criar o pool de identidade da carga de trabalho.
    • WORKLOAD_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.
    • WORKLOAD_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 identidade da carga de trabalho posteriormente.

    A formatação do URI dessa maneira garante que o identificador da parte confiável identifique exclusivamente um provedor de pool de identidade da carga de trabalho.

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

  11. Clique em Próxima.

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

  13. Na página Tudo pronto para adicionar confiança, revise as configurações e clique em Avançar.

  14. 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 declaração que identifique o usuário do Active Directory de maneira exclusiva. Normalmente, é usada a declaraçã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 declarações, faça isto:

  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 declaração de transformação, faça isto:
    1. Selecione Transformar uma reivindicação recebida.
    2. Clique em Próxima.

  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.

Configurar a federação de identidade da carga de trabalho

Você só precisa realizar essas etapas uma vez por locatário do ID do Microsoft Entra ou conta da AWS com que pretende federar. Depois disso, será possível usar o mesmo pool de identidade da carga de trabalho e servidor em várias cargas de trabalho e em vários projetos do Google Cloud.

Para começar a configurar a federação de identidade da carga de trabalho, faça isto:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    2. É melhor usar um projeto dedicado para gerenciar pools e provedores de identidade da carga de trabalho

  2. Make sure that billing is enabled for your Google Cloud project.

    3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

    Enable the APIs

Definir um mapeamento e uma condição de atributo

As credenciais específicas do ambiente da carga de trabalho da AWS ou do Azure contêm vários atributos, e você precisa decidir qual atributo quer usar como identificador do assunto (google.subject) no Google Cloud.

Também é possível mapear outros atributos. Consulte esses atributos adicionais ao conceder acesso aos recursos.

OIDC

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.

SAML ou confiança WS

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 declaração do 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. Por 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 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.

OIDC

Use uma condição de atributo para restringir quais clientes podem usar a federação de identidade da carga de trabalho para conseguir tokens de curta duração do Google Cloud.

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 ou confiança WS

Use uma condição de atributo para restringir quais usuários do Active Directory podem usar a federação de identidade da carga de trabalho para conseguir tokens de curta duração do Google Cloud.

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

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:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

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.

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. Defina as configurações do provedor:

    OIDC

    • Selecione um provedor: OpenID Connect (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: https://ADFS_DOMAIN/adfs, em que ADFS_DOMAIN é o nome do domínio público do servidor ou farm do AD FS.

    SAML

    Para configurar a federação de identidade da carga de trabalho de um IdP compatível com SAML 2.0, use as instruções da gcloud CLI.

  5. Clique em Continuar.

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

  7. 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.

  8. 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 WORKLOAD_POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"

    Substitua:

    • WORKLOAD_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:

    OIDC 

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

    Substitua:

    O prefixo gcp- é reservado e não pode ser usado em um ID de provedor ou de pool de identidades da força de trabalho.

    SAML ou confiança WS 

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

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

    Substitua:

    O prefixo gcp- é reservado e não pode ser usado em um ID de provedor ou de pool de identidades da força de trabalho.

    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"

    Opcional: aceitar declarações SAML criptografadas do seu IdP

    Para permitir que o IdP do SAML 2.0 produza declarações SAML criptografadas que podem ser aceitas pela federação de identidade da carga de trabalho, faça isto:

    • Na federação de identidade da carga de trabalho, faça isto:
      • Crie um par de chaves assimétricas para seu provedor de pool de identidade da carga de trabalho.
      • Faça o download de um arquivo de certificado que contém a chave pública.
      • Configure o IdP do SAML para que use a chave pública para criptografar as declarações SAML emitidas.
    • No IdP, faça isto:
      • Ative a criptografia de declaração, também conhecida como criptografia de token.
      • Faça upload da chave pública que você criou na federação de identidade da carga de trabalho.
      • Confirme se o IdP produz declarações SAML criptografadas.
    Observação: mesmo com as chaves do provedor de criptografia SAML configuradas, a federação de identidade da carga de trabalho ainda pode processar uma declaração de texto simples.

    Criar chaves de criptografia de declaração SAML da federação de identidade da carga de trabalho

    Nesta seção, mostramos como criar um par de chaves assimétricas que permite que a federação de identidade da carga de trabalho aceite declarações SAML criptografadas.

    O Google Cloud usa a chave privada para descriptografar as declarações SAML emitidas pelo IdP. Para criar um par de chaves assimétricas para uso com criptografia SAML, execute o seguinte comando. Para saber mais, consulte Algoritmos de criptografia SAML compatíveis. 

    gcloud iam workload-identity-pools providers keys create KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider WORKLOAD_PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION

    Substitua:

    • KEY_ID: o nome da chave que você escolher
    • WORKLOAD_POOL_ID: o ID do pool
    • WORKLOAD_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho
    • KEY_SPECIFICATION: a especificação da chave, que pode ser uma destas: rsa-2048, rsa-3072 e rsa-4096.

    Depois que o par de chaves for criado, execute o comando a seguir para fazer o download da chave pública em um arquivo de certificado. Somente a federação de identidade da carga de trabalho tem acesso à chave privada. 

    gcloud iam workload-identity-pools providers keys describe KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider WORKLOAD_PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH

    Substitua:

    • KEY_ID: o nome da chave
    • WORKLOAD_POOL_ID: o ID do pool
    • WORKLOAD_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho
    • CERTIFICATE_PATH: o caminho para gravar o certificado em, por exemplo, saml-certificate.cer ou saml-certificate.pem

    Configurar o IdP compatível com SAML 2.0 para emitir declarações SAML criptografadas

    1. Mova o arquivo de certificado para o servidor do AD FS.
    2. No servidor do AD FS, clique com o botão direito do mouse no botão Iniciar (ou pressione Win+X) e clique em Windows PowerShell (Admin).
    3. No PowerShell, execute o seguinte comando para ativar a criptografia: 
              Set-AdfsRelyingPartyTrust `
        -TargetName NAME `
        -SamlResponseSignature MessageAndAssertion `
        -EncryptionCertificate PATH `
        -EncryptClaims $True

      Substitua:

      • NAME: o nome do objeto de confiança da parte confiável
      • PATH: o caminho do arquivo de certificado

    Usuários do WS-Trust: esse recurso só está disponível quando você usa SAML.

    Depois de configurar o IdP para criptografar declarações SAML, recomendamos que você confira se as declarações geradas estão realmente criptografadas. Mesmo com a criptografia da declaração SAML configurada, a federação de identidade da carga de trabalho ainda pode processar declarações de texto simples.

    Excluir chaves de criptografia da federação de identidade da carga de trabalho

    Para excluir as chaves de criptografia SAML, execute o seguinte comando: 
      gcloud iam workload-identity-pools providers keys delete KEY_ID \
      --workload-identity-pool WORKLOAD_POOL_ID \
      --provider WORKLOAD_PROVIDER_ID \
      --location global

    Substitua:

    • KEY_ID: o nome da chave
    • WORKLOAD_POOL_ID: o ID do pool
    • WORKLOAD_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho

    Algoritmos de criptografia SAML compatíveis

    A federação de identidade da carga de trabalho é compatível com os seguintes algoritmos de transporte de chaves:

    A federação de identidade da carga de trabalho é compatível com os seguintes algoritmos de criptografia em blocos:

Opcional: ativar a criptografia SAML

As declarações SAML emitidas pelo AD FS são assinadas criptograficamente e trocadas por um canal TLS criptografado. No entanto, as declarações do SAML não são criptografadas. Ao usar a criptografia SAML, é possível configurar o AD FS para criptografar declarações, de modo que elas só possam ser descriptografadas e lidas pelo pool de identidades da carga de trabalho.

OIDC

Esse recurso só está disponível ao usar o SAML.

SAML ou confiança WS

  1. Crie uma chave de criptografia para o provedor do pool de identidade da carga de trabalho:

    gcloud iam workload-identity-pools providers keys create rsa2048 \
    --workload-identity-pool=POOL_ID \
    --provider=WORKLOAD_PROVIDER_ID \
    --location=global \
    --use=ENCRYPTION \
    --spec=RSA_2048

    Substitua:

    • WORKLOAD_PROVIDER_ID: ID do provedor.
    • POOL_ID: o ID do pool.

    O par de chaves é armazenado e gerenciado pela federação de identidade da carga de trabalho. É possível exportar a chave pública, mas apenas a federação de identidade da carga de trabalho pode acessar a chave privada.

  2. Exporte um certificado que contém a chave pública:

    gcloud iam workload-identity-pools providers keys describe rsa2048 \
    --workload-identity-pool=POOL_ID \
    --provider=WORKLOAD_PROVIDER_ID \
    --location=global \
    --format="value(keyData.key)" > workload-identity-federation.cer

  3. Mova o arquivo de certificado para o servidor do AD FS.

  4. No servidor do AD FS, clique com o botão direito do mouse em Iniciar e, em seguida, em Windows PowerShell (administrador).

  5. No PowerShell, modifique a confiança da parte confiável para que ela use a criptografia:

    Set-AdfsRelyingPartyTrust `
  -TargetName NAME `
  -SamlResponseSignature MessageAndAssertion `
  -EncryptionCertificate PATH `
  -EncryptClaims $True

    Substitua:

    • NAME: o nome do objeto de confiança da parte confiável
    • PATH: o caminho do arquivo de certificado

Autenticar uma carga de trabalho

É necessário realizar essas etapas uma vez por carga de trabalho.

Permitir que a carga de trabalho externa acesse recursos do Google Cloud

Para fornecer à sua carga de trabalho acesso aos recursos do Google Cloud, recomendamos que você conceda ao principal acesso direto aos recursos. Nesse caso, o principal é o usuário federado. Alguns produtos do Google Cloud têm limitações de APIs do Google Cloud. Se sua carga de trabalho chamar um endpoint de API que apresenta limitação, será possível usar a identidade temporária de conta de serviço. Nesse caso, o principal é a conta de serviço do Google Cloud, que atua como a identidade. Você concede acesso à conta de serviço no recurso.

Acesso direto a recursos

É possível conceder acesso a uma identidade federada diretamente nos recursos usando o console do Google Cloud ou a gcloud CLI.

Console

Para usar o console do Google Cloud para conceder papéis do IAM diretamente em um recurso, acesse a página do recurso e conceda o papel. O exemplo a seguir mostra como acessar a página do Cloud Storage e conceder o papel Leitor de objetos do Storage (roles/storage.objectViewer) a uma identidade federada diretamente em um bucket do Cloud Storage.

  1. No Console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket ao qual você quer conceder o papel.

  3. Selecione a guia Permissões na parte superior da página.

  4. Clique no botão Permitir acesso.

    A caixa de diálogo Adicionar principais será exibida.

  5. No campo Novos principais, insira uma ou mais identidades que precisam acessar seu bucket.

    Por assunto 

    principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

    Substitua:

    • PROJECT_NUMBER: o número do projeto
    • POOL_ID: o ID do pool de carga de trabalho
    • SUBJECT: o sujeito individual mapeado do IdP, por exemplo, administrator@example.com

    Por grupo 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

    Substitua:

    • PROJECT_NUMBER: o número do projeto
    • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
    • GROUP: o grupo mapeado do IdP, por exemplo: administrator-group@example.com

    Por atributo 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

    Substitua:

    • PROJECT_NUMBER: o número do projeto
    • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
    • ATTRIBUTE_NAME: um dos atributos que foi mapeado do IdP
    • ATTRIBUTE_VALUE: o valor do atributo

  6. Escolha um papel ou mais no menu suspenso Selecionar um papel. Os papéis selecionados são exibidos no painel com uma breve descrição das permissões que eles concedem.

  7. Clique em Salvar.

gcloud

Para usar a gcloud CLI a fim de conceder papéis do IAM em um recurso de um projeto, faça isto:

  1. Consiga o número do projeto em que o recurso está definido.

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)

  2. Conceda acesso ao recurso.

    Para usar a gcloud CLI para conceder o papel de leitor de objetos de armazenamento (roles/storage.objectViewer) a identidades externas que atendam a determinados critérios, execute o comando a seguir.

    Por assunto

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

    Por grupo

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

    Por atributo

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

    Substitua:

    • BUCKET_ID: o bucket em que o acesso será concedido
    • PROJECT_NUMBER: o número do projeto que contém o pool de Identidade da carga de trabalho
    • POOL_ID: o ID do pool de identidade da carga de trabalho
    • SUBJECT: o valor esperado do atributo mapeado para google.subject
    • GROUP: o valor esperado do atributo mapeado para google.groups
    • ATTRIBUTE_NAME: o nome de um atributo personalizado no seu mapeamento de atributos
    • ATTRIBUTE_VALUE: o valor do atributo personalizado no seu mapeamento de atributos

    É possível conceder papéis em qualquer recurso do Google Cloud compatível com políticas de permissão do IAM.

Identidade temporária de conta de serviço

  1. Para criar uma conta de serviço para a carga de trabalho externa, faça isto:

    1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

      Enable the APIs

    2. Crie uma conta de serviço que represente a carga de trabalho. Recomendamos que você use uma conta de serviço dedicada para cada carga de trabalho. A conta de serviço não precisa estar no mesmo projeto que o pool de Identidade da carga de trabalho, mas você precisa se referir ao projeto que contém a conta de serviço.

    3. Conceda à conta de serviço acesso a recursos que você quer que as identidades externas acessem.

    4. Conceda a função do usuário de Identidade da carga de trabalho (roles/iam.workloadIdentityUser) à conta de serviço:

  2. Para conceder acesso a uma identidade federada usando a identidade temporária de conta de serviço pelo console do Google Cloud ou pela gcloud CLI:

Console

Para usar o console do Google Cloud para conceder papéis do IAM a uma identidade federada com conta de serviço, faça isto:

Conta de serviço no mesmo projeto

  1. Para conceder acesso usando a identidade temporária de conta de serviço no mesmo projeto, faça o seguinte:

    1. Acesse a página pools de Identidade da carga de trabalho.

      Acesse Pools de identidade da carga de trabalho

    2. Selecione Conceder acesso.

    3. Na caixa de diálogo Conceder acesso à conta de serviço, selecione Conceder acesso usando a identidade temporária de conta de serviço.

    4. Na lista Contas de serviço, selecione a conta de serviço para as identidades externas que serão representadas e faça isto:

    5. Para escolher quais identidades no pool podem representar a conta de serviço, realize uma das seguintes ações:

      • Para permitir que apenas identidades específicas do pool de Identidade da carga de trabalho representem a conta de serviço, selecione Somente identidades correspondentes ao filtro.

      • Na lista Nome do atributo, selecione o atributo que você quer filtrar.

      • No campo Valor do atributo, insira o valor esperado do atributo. Por exemplo, se você usar um google.subject=assertion.sub de mapeamento de atributos, defina o nome do Atributo com subject e o Valor do atributo com o valor da declaração sub em tokens emitidos pelo seu provedor de identidade externo.

    6. Para salvar a configuração, clique em Salvar e em Dispensar.

Conta de serviço em um projeto diferente

  1. Para conceder acesso usando a identidade temporária de conta de serviço em um projeto diferente, faça o seguinte:

    1. Acesse a página Contas de serviço.

      Acessar a página "Contas de serviço"

    2. Selecione a conta de serviço que você quer representar.

    3. Clique em Gerenciar acesso.

    4. Clique em Adicionar principal.

    5. No campo Novo principal, insira um dos seguintes identificadores principais para as identidades no pool que vão representar a identidade da conta de serviço.

      Por assunto 

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • POOL_ID: o ID do pool de carga de trabalho
      • SUBJECT: o sujeito individual mapeado do IdP, por exemplo, administrator@example.com

      Por grupo 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
      • GROUP: o grupo mapeado do IdP, por exemplo: administrator-group@example.com

      Por atributo 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
      • ATTRIBUTE_NAME: um dos atributos que foi mapeado do IdP
      • ATTRIBUTE_VALUE: o valor do atributo

      Por pool

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho

    6. Em Selecionar um papel, selecione a função de usuário da Identidade da carga de trabalho (roles/iam.workloadIdentityUser).

    7. Para salvar a configuração, clique em Salvar.

gcloud

Para usar a gcloud CLI para conceder o papel Usuário de Identidade da carga de trabalho (roles/iam.workloadIdentityUser) a identidades externas que atendam a determinados critérios, execute o comando a seguir.

Por assunto

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

Por grupo

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

Por atributo

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Substitua:

  • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço
  • PROJECT_NUMBER: o número do projeto que contém o pool de Identidade da carga de trabalho
  • POOL_ID: o ID do pool de identidade da carga de trabalho
  • SUBJECT: o valor esperado do atributo mapeado para google.subject
  • GROUP: o valor esperado do atributo mapeado para google.groups
  • ATTRIBUTE_NAME: o nome de um atributo personalizado no seu mapeamento de atributos
  • ATTRIBUTE_VALUE: o valor do atributo personalizado no seu mapeamento de atributos

Criar uma configuração de credencial

É possível permitir que as bibliotecas de cliente do Cloud e as ferramentas como a CLI gcloud e o Terraform usem credenciais do Active Directory para fazer a autenticação no Google Cloud com o Autenticador de carga de trabalho do Windows

O Workload Authenticator para Windows é uma ferramenta de código aberto que funciona como um plug-in para as bibliotecas de cliente do Cloud e ferramentas como a CLI gcloud:

  1. Quando a ferramenta ou biblioteca precisar de uma nova credencial, ela iniciará o autenticador da carga de trabalho em segundo plano.
  2. O autenticador de carga de trabalho usa OIDC, SAML ou WS-Trust para receber um novo token ou declaração SAML do AD FS e o transmite de volta à ferramenta ou biblioteca.
  3. A ferramenta ou biblioteca usa trocas de tokens ou declarações SAML em credenciais do Google Cloud de curta duração usando a federação de identidade da carga de trabalho.

Para usar o autenticador de carga de trabalho para Windows, é preciso criar um arquivo de configuração de credencial. Esse arquivo define o seguinte:

  • Onde encontrar o autenticador de carga de trabalho para Windows (wwauth.exe) e com quais parâmetros executá-lo
  • Qual pool de identidades de carga de trabalho e provedor usar
  • Qual conta de serviço representar

Para criar um arquivo de configuração de credenciais, faça isto no Windows Server que executa a carga de trabalho:

  1. Clique com o botão direito do mouse no botão Iniciar (ou pressione Win+X) e clique em Windows PowerShell.

  2. Faça o download do Autenticador de cargas de trabalho para Windows e salve-o em um local acessível pela sua carga de trabalho:

    (New-Object Net.WebClient).DownloadFile(
  "https://github.com/GoogleCloudPlatform/iam-windows-authenticator/releases/latest/download/wwauth.exe",
  "${env:ProgramData}\wwauth.exe")

    Se você criar um arquivo de configuração de credencial usando o autenticador de carga de trabalho do Windows, o arquivo conterá o caminho para o executável. Se você mais tarde excluir ou mover o executável, as cargas de trabalho não vão poder encontrá-lo nem usá-lo.

  3. Lançamento wwauth.exe:

    & ${env:ProgramData}\wwauth.exe

    Uma caixa de diálogo de configuração é aberta.

    Autenticador de carga de trabalho

  4. Selecione a guia AD FS e insira as seguintes configurações:

    • URI do emissor do servidor do AD FS: URI público do servidor ou farm do AD FS.

      https://ADFS_DOMAIN/adfs/

      Substitua ADFS_DOMAIN pelo nome de domínio público do servidor do AD FS ou do farm de servidores.

    As próximas configurações dependem do protocolo que você quer usar:

    OIDC

    • Protocolo: AdfsOidc
    • ID da entidade confiável: mantenha o padrão.
    • ID do cliente identificador do cliente (ID do cliente) do aplicativo do servidor no AD FS.

    SAML

    • Protocolo: AdfsSamlPost
    • Assertion consumer service URL: https://sts.googleapis.com/v1/token.
    • Assinar solicitações usando o certificado: desativado

    Confiança WS

    • Protocolo: AdfsWsTrust

  5. Selecione a guia Identidade da carga de trabalho e insira as seguintes configurações:

    • Número do projeto: número do projeto que contém o pool de identidades da carga de trabalho
    • ID do pool: ID do pool de identidades da carga de trabalho
    • ID do provedor: o ID do provedor do pool de identidade da carga de trabalho
    • Representar conta de serviço: ativada, se você usa a identidade temporária de conta de serviço
    • Endereço de e-mail: endereço de e-mail da conta de serviço, se você usa a identidade temporária de conta de serviço

  6. Selecione a guia AD FS e verifique se o campo ID de entidade confiável agora contém o URL do seu provedor de pool de identidade da carga de trabalho.

  7. Clique em Aplicar e escolha um local de arquivo para salvar o arquivo de configuração de credencial.

    Ao contrário de uma chave de conta de serviço, um arquivo de configuração de credenciais não contém secrets e não precisa ser mantido em sigilo. Veja detalhes sobre o arquivo de configuração de credenciais em https://google.aip.dev/auth/4117.

Agora está tudo pronto para testar a configuração:

  1. Selecione um usuário do Active Directory para testar. Pode ser o usuário do Active Directory da carga de trabalho ou o usuário com o qual você fez login.

  2. Para testar a configuração com seu usuário atual, clique em Testar.

    Para testar com um usuário diferente, selecione Testar > Testar configuração como usuário e insira as credenciais para o usuário.

    Agora, a ferramenta tenta se autenticar no Google Cloud seguindo estas etapas:

    1. Receber um token OIDC ou declaração SAML do AD FS.
    2. Receber um token do Google Security Token Service.
    3. Representar a conta de serviço se você usa a identidade temporária de conta de serviço.

    Se a autenticação for bem-sucedida, você verá a mensagem Teste concluído com sucesso:

    Resultado do teste

Usar a configuração de credencial para acessar o Google Cloud

Para permitir que as ferramentas e as bibliotecas de cliente usem a configuração da sua credencial, faça o seguinte no Windows Server que executa a carga de trabalho:

  1. Clique com o botão direito do mouse no botão Start e clique em Run.
  2. Insira sysdm.cpl e clique em OK.
  3. Na guia Avançado, clique em Variáveis de ambiente.

  4. Na seção Variáveis do sistema, adicione duas novas variáveis:

    Nome Valor
    GOOGLE_APPLICATION_CREDENTIALS Caminho para o arquivo de configuração de credenciais
    GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 1

  5. Clique em OK.

  6. Use uma biblioteca de cliente ou ferramenta compatível com a federação de identidade da carga de trabalho e que possa encontrar credenciais automaticamente:

    C++

    As bibliotecas de cliente do Google Cloud para C++ são compatíveis com a federação de identidade da carga de trabalho desde a versão v2.6.0. Para usar a federação de identidade da carga de trabalho, crie as bibliotecas de cliente com a versão 1.36.0 ou mais recente do gRPC.

    Go

    As bibliotecas de cliente do Go são compatíveis com a federação de identidade da carga de trabalho se usarem a versão v0.0.0-20210218202405-ba52d332ba99 ou posteriores do módulo golang.org/x/oauth2.

    Para verificar qual versão deste módulo sua biblioteca de cliente usa, execute os seguintes comandos:

    cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2

    Java

    As bibliotecas de cliente do Java aceitam federação de identidade da carga de trabalho se usarem a versão 0.24.0 ou posteriores do artefato com.google.auth:google-auth-library-oauth2-http.

    Para verificar qual versão desse artefato a biblioteca de cliente usa, execute o seguinte comando do Maven no diretório do aplicativo:

    mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http

    Node.js

    As bibliotecas de cliente do Node.js são compatíveis com a federação de identidade da carga de trabalho se usarem a versão 7.0.2 ou posteriores do pacote google-auth-library.

    Para verificar qual versão desse pacote sua biblioteca de cliente usa, execute o seguinte comando no diretório do seu aplicativo:

    npm list google-auth-library

    Ao criar um objeto GoogleAuth, é possível especificar um ID de projeto ou permitir que GoogleAuth encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no arquivo de configuração precisa ter o papel de navegador (roles/browser), ou um papel com permissões equivalentes no projeto. Para ver detalhes, consulte o README do pacote google-auth-library.

    Python

    As bibliotecas de cliente do Python são compatíveis com a federação de identidade da carga de trabalho se usarem a versão 1.27.0 ou posteriores do pacote google-auth.

    Para verificar qual versão desse pacote sua biblioteca de cliente usa, execute o seguinte comando no ambiente em que o pacote está instalado:

    pip show google-auth

    Para especificar um ID de projeto para o cliente de autenticação, defina a variável de ambiente GOOGLE_CLOUD_PROJECT ou permita que o cliente encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no arquivo de configuração precisa ter o papel de Navegador (roles/browser) ou um papel com permissões equivalentes no projeto. Para ver detalhes, consulte o guia do usuário do pacote google-auth.

    gcloud

    Para autenticar usando a federação de identidade da carga de trabalho, use o comando gcloud auth login:

    gcloud auth login --cred-file=FILEPATH.json

    Substitua FILEPATH pelo caminho para o arquivo de configuração de credencial.

    O suporte para a federação de identidade da carga de trabalho na gcloud CLI está disponível na versão 363.0.0 e posteriores da gcloud CLI.

    Terraform

    O provedor do Google Cloud é compatível com a federação de identidade da carga de trabalho se você usar a versão 3.61.0 ou posterior:

    terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 3.61.0"
    }
  }
}

    bq

    Para autenticar usando a federação de identidade da carga de trabalho, use o comando gcloud auth login da seguinte maneira:

    gcloud auth login --cred-file=FILEPATH.json

    Substitua FILEPATH pelo caminho para o arquivo de configuração de credencial.

    O suporte para a federação de identidade da carga de trabalho no bq está disponível na versão 390.0.0 e posteriores da gcloud CLI.

A seguir