Configurar a federação de identidade de colaboradores

Este guia descreve como configurar a federação de identidade de colaboradores com um provedor de identidade (IdP) compatível com OIDC ou SAML 2.0.

Para instruções específicas sobre o IdP, consulte:

• Configurar a federação de identidade de colaboradores com base no ID do Microsoft Entra
• Configurar a federação de identidade de colaboradores da Okta

Antes de começar

1. Você precisa ter uma organização do Google Cloud configurada.

2. Enable the Identity and Access Management (IAM) and Resource Manager APIs.

   Enable the APIs

3. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

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

5. Para receber informações importantes sobre mudanças na sua organização ou nos produtos do Google Cloud, forneça os Contatos essenciais. Para mais detalhes, consulte as informações gerais da federação de identidade de colaboradores.

Funções exigidas

Para receber as permissões necessárias para configurar a federação de identidade de colaboradores, peça ao administrador para conceder a você o papel do IAM Administrador de pool de colaboradores do IAM (roles/iam.workforcePoolAdmin) na organização. 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 (roles/owner) também inclui permissões para configurar a federação de identidade de colaboradores. 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 de teste.

Configurar a federação de identidade de colaboradores

Para configurar a federação de identidade de colaboradores, crie um pool de identidade de colaboradores e um provedor de pool de identidade de colaboradores.

Criar um pool de identidades de colaboradores

Execute o comando a seguir para criar o pool:

Console

Para criar o pool de identidades de colaboradores, faça o seguinte:

1. No console do Google Cloud, acesse a página Pools de identidade da força de trabalho:

   Acessar pools de identidade de colaboradores

2. Clique em Criar pool e faça o seguinte:

   1. No campo Nome, digite o nome de exibição do pool. O ID do pool é derivado automaticamente do nome à medida que você digita e é exibido no campo Nome. Para atualizar o ID do pool, clique em Editar ao lado dele.

   2. Opcional: em Descrição, insira uma descrição do pool.

   3. A duração da sessão é definida por padrão. Para inserir uma duração personalizada da sessão, clique em Editar. A duração da sessão, que determina por quanto tempo os tokens de acesso do Google Cloud, as sessões de login do console (federado) e o login da CLI gcloud deste pool de forças de trabalho são válidas. A duração precisa ser maior que 15 minutos (900s) e menor que 12 horas (43200s). Se a duração da sessão não for definida, o padrão será de uma hora (3.600 segundos).

   4. Para criar o pool no estado ativado, verifique se a opção Pool ativado está ativada.

   5. Para criar o pool de identidades de colaboradores, clique em Próxima.

gcloud

Para criar o pool de identidade de colaboradores, execute o seguinte comando:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

Substitua:

• WORKFORCE_POOL_ID: um ID que você quer representar no seu pool de forças de trabalho do Google Cloud. Para informações sobre como formatar o ID, consulte a seção Parâmetros de consulta na documentação da API.
• ORGANIZATION_ID: o ID numérico da organização do Google Cloud.
• DISPLAY_NAME: opcional. Um nome de exibição para o pool de identidade de colaboradores.
• DESCRIPTION: opcional. Uma descrição do pool de identidade de colaboradores.
• SESSION_DURATION: opcional. A duração da sessão, que determina por quanto tempo os tokens de acesso do Google Cloud, as sessões de login do, console (federado) e o login da gcloud CLI deste pool de força de trabalho são válidos. A duração precisa ser maior que 15 minutos (900s) e menor que 12 horas (43200s). Se a duração da sessão não for definida, o padrão será de uma hora (3.600 segundos).

Dica: execute gcloud iam workforce-pools create --help para encontrar outros parâmetros que podem ser personalizados para esse comando.

Criar um provedor de pool de identidade de força de trabalho

Nesta seção, descrevemos como criar um provedor de pool de identidade de colaboradores para permitir que os usuários do IdP acessem o Google Cloud. É possível configurar o provedor para usar o protocolo OIDC ou SAML.

Criar um provedor de pool de força de trabalho OIDC

Para criar um provedor de pool de identidade de colaboradores usando o protocolo OIDC, faça o seguinte:

1. No IdP OIDC, registre um novo aplicativo para a federação de identidade de colaboradores do Google Cloud. Observe o ID do cliente e o URI do emissor, fornecidos pelo IdP. Eles serão usados neste documento.

2. Se você planeja configurar o acesso do usuário ao console, adicione o URL de redirecionamento a seguir ao seu IdP do OIDC:

   https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
   

   Para saber como configurar o login no console (federado), consulte Configurar o acesso do usuário ao console (federado).

3. No Google Cloud, para criar o provedor, faça o seguinte:

   Console

   Fluxo de códigos

   No console do Google Cloud, para criar um provedor OIDC que usa o fluxo do código de autorização, faça o seguinte:

   1. No console do Google Cloud, acesse a página Pools de identidade da força de trabalho:

      Acessar pools de identidade de colaboradores

   2. Na tabela Pools de identidade de colaboradores, selecione o pool em que você quer criar o provedor.

   3. Na tabela Provedores, clique em Adicionar provedor.

   4. Em Selecionar um protocolo, selecione Open ID Connect (OIDC).

   5. Em Criar um provedor de pool, faça o seguinte:

      1. Em Nome, digite um nome para o provedor.
      2. Em Emissor (URL), insira o URI do emissor. O URI do emissor do OIDC precisa estar em um formato de URI válido e começar com https. por exemplo, https://example.com/oidc.
      3. Digite o ID do cliente, o ID do cliente OIDC registrado no seu IdP OIDC. o ID precisa corresponder à declaração aud do JWT emitido pelo IdP.
      4. Para criar um provedor ativado, verifique se Provedor ativado está ativado.
      5. Clique em Continuar.

   6. Em Tipo de resposta, faça o seguinte. O tipo de resposta é usado apenas para um fluxo de Logon único baseado na Web.

      1. Em Tipo de resposta, selecione Código.
      2. Em Chave secreta do cliente, digite a chave secreta do cliente no IdP.

      3. Em Comportamento das reivindicações de declaração, selecione uma das seguintes opções:

         • Token de ID e informações do usuário
         • Somente o token de ID

      4. Clique em Continuar.

   7. Em Configurar provedor, é possível configurar um mapeamento e uma condição de atributo. Para criar um mapeamento de atributo, faça o seguinte. É possível fornecer o nome do campo do IdP ou uma expressão formatada em CEL que retorne uma string.

      1. Obrigatório: no OIDC 1, digite o assunto do IdP. por exemplo, assertion.sub.

      2. Opcional: para adicionar outros mapeamentos de atributos, faça o seguinte:

         1. Clique em Adicionar mapeamento.
         2. No Google n, em que n é um número, insira uma das chaves compatíveis com o Google Cloud. de dois minutos.
         3. No campo OIDC n correspondente, insira o nome do campo específico do IdP a ser mapeado, no formato CEL.

      3. Para criar uma condição de atributo, faça o seguinte:

         Aviso:se o IdP multisseção tiver um único URI de emissor, use condições de atributo para garantir que o acesso seja restrito ao locatário correto. Para mais informações, consulte Usar condições de atributos ao federar com o GitHub ou outros provedores de identidade multilocatários.
         1. Clique em Adicionar condição.
         2. Em Condições do atributo, insira uma condição no formato CEL. Por exemplo, assertion.role == 'gcp-users'. Este exemplo de condição garante que apenas os usuários com o papel gcp-users possam fazer login usando este provedor.

   8. Para criar o provedor, clique em Enviar.

   Fluxo implícito

   No console do Google Cloud, para criar um provedor OIDC que usa fluxo implícito, faça o seguinte:

   1. No console do Google Cloud, acesse a página Pools de identidade da força de trabalho:

      Acessar pools de identidade de colaboradores

   2. Na tabela Pools de identidade de colaboradores, selecione o pool em que você quer criar o provedor.

   3. Na tabela Provedores, clique em Adicionar provedor.

   4. Em Selecionar um protocolo, selecione Open ID Connect (OIDC).

   5. Em Criar um provedor de pool, faça o seguinte:

      1. Em Nome, digite um nome para o provedor.
      2. Em Emissor (URL), insira o URI do emissor. O URI do emissor do OIDC precisa estar em um formato de URI válido e começar com https. por exemplo, https://example.com/oidc.
      3. Digite o ID do cliente, o ID do cliente OIDC registrado no seu IdP OIDC. o ID precisa corresponder à declaração aud do JWT emitido pelo IdP.
      4. Para criar um provedor ativado, verifique se Provedor ativado está ativado.
      5. Clique em Continuar.

   6. Em Tipo de resposta, faça o seguinte. O tipo de resposta é usado apenas para um fluxo de Logon único baseado na Web.

      1. Em Tipo de resposta, selecione Token de ID.
      2. Clique em Continuar.

   7. Em Configurar provedor, é possível configurar um mapeamento e uma condição de atributo. Para criar um mapeamento de atributo, faça o seguinte. É possível fornecer o nome do campo do IdP ou uma expressão formatada em CEL que retorne uma string.

      1. Obrigatório: no OIDC 1, digite o assunto do IdP. por exemplo, assertion.sub.

      2. Opcional: para adicionar outros mapeamentos de atributos, faça o seguinte:

         1. Clique em Adicionar mapeamento.
         2. No Google n, em que n é um número, insira uma das chaves compatíveis com o Google Cloud. de dois minutos.
         3. No campo OIDC n correspondente, insira o nome do campo específico do IdP a ser mapeado, no formato CEL.

      3. Para criar uma condição de atributo, faça o seguinte:

         1. Clique em Adicionar condição.

         2. Em Condições do atributo, insira uma condição no formato CEL. Por exemplo, assertion.role == 'gcp-users'. Este exemplo de condição garante que apenas os usuários com o papel gcp-users possam fazer login usando este provedor.

            Aviso:se o IdP multisseção tiver um único URI de emissor, use condições de atributo para garantir que o acesso seja restrito ao locatário correto. Para mais informações, consulte Usar condições de atributos ao federar com o GitHub ou outros provedores de identidade multilocatários.

   8. Para criar o provedor, clique em Enviar.

   gcloud

   Fluxo de códigos

   Para criar um provedor do OIDC que usa o fluxo do código de autorização para login na Web, execute o seguinte comando:

   gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --display-name="DISPLAY_NAME" \
       --description="DESCRIPTION" \
       --issuer-uri="ISSUER_URI" \
       --client-id="OIDC_CLIENT_ID" \
       --client-secret-value="OIDC_CLIENT_SECRET" \
       --web-sso-response-type="code" \
       --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \
       --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
       --attribute-mapping="ATTRIBUTE_MAPPING" \
       --attribute-condition="ATTRIBUTE_CONDITION" \
       --jwk-json-path="JWK_JSON_PATH" \
       --location=global
   

   Substitua:

   • PROVIDER_ID: um ID de provedor exclusivo. O prefixo gcp- é reservado e não pode ser usado em um ID de pool ou de provedor.
   • WORKFORCE_POOL_ID: o ID do pool de identidades de colaboradores para conectar seu IdP.
   • DISPLAY_NAME é um nome de exibição fácil de usar para o provedor. Por exemplo, idp-eu-employees.
   • DESCRIPTION: uma descrição opcional do provedor de colaboradores. Por exemplo, IdP for Partner Example Organization employees
   • ISSUER_URI: o URI do emissor do OIDC, em um formato de URI válido, que começa com https, por exemplo, https://example.com/oidc. Observação: por motivos de segurança, ISSUER_URI precisa usar o esquema HTTPS.
   • OIDC_CLIENT_ID: o ID do cliente do OIDC registrado no IdP do OIDC; o ID precisa corresponder à declaração aud do JWT emitido pelo IdP.
   • OIDC_CLIENT_SECRET: a chave secreta do cliente do OIDC
   • WEB_SSO_ADDITIONAL_SCOPES: escopos extras opcionais a serem enviados ao IdP do OIDC para o console (federado) ou o login baseado no navegador da gcloud CLI
   • ATTRIBUTE_MAPPING: um mapeamento de atributo. Confira a seguir um exemplo de mapeamento de atributos:

     google.subject=assertion.sub,
     google.groups=assertion.group1,
     attribute.costcenter=assertion.costcenter

     Neste exemplo, os atributos do IdP subject, group1, e costcenter na declaração OIDC são mapeados para os atributos google.subject, google.groups e attribute.costcenter, respectivamente. de dois minutos.
   • ATTRIBUTE_CONDITION: uma condição do atributo. Por exemplo: assertion.role == 'gcp-users'. Este exemplo de condição garante que apenas os usuários com o papel gcp-users possam fazer login usando este provedor.
   Aviso:se o IdP multisseção tiver um único URI de emissor, use condições de atributo para garantir que o acesso seja restrito ao locatário correto. Para mais informações, consulte Usar condições de atributos ao federar com o GitHub ou outros provedores de identidade multilocatários.
   • JWK_JSON_PATH: um caminho opcional para JWKs do OIDC de upload local. Se esse parâmetro não for fornecido, o Google Cloud usará o caminho /.well-known/openid-configuration do IdP para gerar as JWKs que contêm as chaves públicas. Para mais informações sobre JWKs OIDC enviados localmente, consulte Gerenciar JWKs OIDC.

   Observação: é possível fazer upload de JWKs do OIDC locais por fluxo implícito ou fluxo de código, mas só pode ser usado no fluxo programático, em que você chama diretamente o endpoint do STS /token com uma credencial do IdP de terceiros para trocar por um Google Cloud. token de acesso para o pool da força de trabalho.

   Na resposta ao comando, POOL_RESOURCE_NAME é o nome do pool. Por exemplo, locations/global/workforcePools/enterprise-example-organization-employees.

   Fluxo implícito

   Para criar um provedor do OIDC que usa o fluxo implícito para login na Web, execute o seguinte comando:

   gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --display-name="DISPLAY_NAME" \
       --description="DESCRIPTION" \
       --issuer-uri="ISSUER_URI" \
       --client-id="OIDC_CLIENT_ID" \
       --web-sso-response-type="id-token" \
       --web-sso-assertion-claims-behavior="only-id-token-claims" \
       --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
       --attribute-mapping="ATTRIBUTE_MAPPING" \
       --attribute-condition="ATTRIBUTE_CONDITION" \
       --jwk-json-path="JWK_JSON_PATH" \
       --location=global
   

   Substitua:

   • PROVIDER_ID: um ID de provedor exclusivo. O prefixo gcp- é reservado e não pode ser usado em um ID de pool ou de provedor.
   • WORKFORCE_POOL_ID: o ID do pool de identidades de colaboradores para conectar seu IdP.
   • DISPLAY_NAME é um nome de exibição fácil de usar para o provedor. Por exemplo, idp-eu-employees.
   • DESCRIPTION: uma descrição opcional do provedor de colaboradores. Por exemplo, IdP for Partner Example Organization employees
   • ISSUER_URI: o URI do emissor do OIDC, em um formato de URI válido, que começa com https, por exemplo, https://example.com/oidc. Observação: por motivos de segurança, ISSUER_URI precisa usar o esquema HTTPS.
   • OIDC_CLIENT_ID: o ID do cliente do OIDC registrado no IdP do OIDC; o ID precisa corresponder à declaração aud do JWT emitido pelo IdP.
   • WEB_SSO_ADDITIONAL_SCOPES: escopos extras opcionais a serem enviados ao IdP do OIDC para o console (federado) ou o login baseado no navegador da gcloud CLI
   • ATTRIBUTE_MAPPING: um mapeamento de atributo. Confira a seguir um exemplo de mapeamento de atributos:

     google.subject=assertion.sub,
     google.groups=assertion.group1,
     attribute.costcenter=assertion.costcenter

     Neste exemplo, os atributos do IdP subject, group1, e costcenter na declaração OIDC são mapeados para os atributos google.subject, google.groups e attribute.costcenter, respectivamente. de dois minutos.
   • ATTRIBUTE_CONDITION: uma condição do atributo. Por exemplo: assertion.role == 'gcp-users'. Este exemplo de condição garante que apenas os usuários com o papel gcp-users possam fazer login usando este provedor.
   Aviso:se o IdP multisseção tiver um único URI de emissor, use condições de atributo para garantir que o acesso seja restrito ao locatário correto. Para mais informações, consulte Usar condições de atributos ao federar com o GitHub ou outros provedores de identidade multilocatários.
   • JWK_JSON_PATH: um caminho opcional para JWKs do OIDC de upload local. Se esse parâmetro não for fornecido, o Google Cloud usará o caminho /.well-known/openid-configuration do IdP para gerar as JWKs que contêm as chaves públicas. Para mais informações sobre JWKs OIDC enviados localmente, consulte Gerenciar JWKs OIDC.

   Observação: é possível fazer upload de JWKs do OIDC locais por fluxo implícito ou fluxo de código, mas só pode ser usado no fluxo programático, em que você chama diretamente o endpoint do STS /token com uma credencial do IdP de terceiros para trocar por um Google Cloud. token de acesso para o pool da força de trabalho.

   Na resposta ao comando, POOL_RESOURCE_NAME é o nome do pool. Por exemplo, locations/global/workforcePools/enterprise-example-organization-employees.

   O prefixo gcp- é reservado e não pode ser usado em um ID de pool ou de provedor.

   Para a federação do OIDC, é possível usar assertion.NAME: uma string igual ao valor da declaração com nome semelhante no payload do token de ID.

Criar um provedor de pool de colaboradores SAML

1. No IdP SAML, registre um novo aplicativo para a federação de identidade de colaboradores do Google Cloud.

2. Defina o público-alvo das declarações SAML. Geralmente, é o campo SP Entity ID na configuração do IdP. Defina-o para o seguinte URL:

   https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID
   

3. Se você planeja configurar o acesso do usuário ao console, no IdP SAML, defina o URL de redirecionamento ou o campo do URL do serviço de declaração de consumidor (ACS) para o seguinte URL:

   https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
   

   Consulte Configurar o acesso do usuário ao console para mais detalhes sobre como configurar o login do console.

4. No Google Cloud, crie um provedor de pool de identidade de colaboradores SAML usando o documento de metadados SAML do IdP. É possível fazer o download do documento XML de metadados SAML no seu IdP. O documento precisa incluir pelo menos o seguinte:

   • Um código de entidade SAML para seu IdP.
   • O URL de Logon único do seu IdP.
   • Pelo menos uma chave pública de assinatura. Consulte Requisitos de chave mais adiante neste guia para saber mais sobre chaves de assinatura.

Console

Para configurar o provedor SAML usando o console do Google Cloud, faça o seguinte:

1. No console do Google Cloud, acesse a página Pools de identidade da força de trabalho:

   Acessar pools de identidade de colaboradores

2. Na tabela Pools de identidade de colaboradores, selecione o pool em que você quer criar o provedor.

3. Na tabela Provedores, clique em Adicionar provedor.

4. Em Selecionar um protocolo, escolha SAML.

5. Em Criar um provedor de pool, faça o seguinte:

   1. Em Nome, digite um nome para o provedor.

   2. Opcional: em Descrição, digite uma descrição para o provedor.

   3. Em Arquivo de metadados do IdP (XML), selecione o arquivo XML de metadados gerado anteriormente neste guia.

   4. Verifique se o Provedor ativado está ativado.

   5. Clique em Continuar.

6. Em Configurar provedor, faça o seguinte:

   1. Em Mapeamento de atributos, insira uma expressão CEL para google.subject.

   2. Opcional: para inserir outros mapeamentos, clique em Adicionar mapeamento e insira outros, por exemplo:

      google.subject=assertion.subject,
      google.groups=assertion.attributes['https://example.com/aliases'],
      attribute.costcenter=assertion.attributes.costcenter[0]

      Este exemplo mapeia os atributos do IdP assertion.subject, assertion.attributes['https://example.com/aliases'] e assertion.attributes.costcenter[0] os atributos do Google Cloud google.subject, google.groups, e google.costcenter, respectivamente.

   3. Opcional: para adicionar uma condição de atributo, clique em Adicionar condição e insira uma expressão CEL que represente uma condição de atributo. Por exemplo, para limitar o atributo ipaddr a um determinado intervalo de IP, defina a condição assertion.attributes.ipaddr.startsWith('98.11.12.'). Este exemplo de condição garante que apenas os usuários com um endereço IP que comece com 98.11.12. possam fazer login usando esse provedor de força de trabalho.

      Aviso:se o IdP multisseção tiver um único URI de emissor, use condições de atributo para garantir que o acesso seja restrito ao locatário correto. Para mais informações, consulte Usar condições de atributos ao federar com o GitHub ou outros provedores de identidade multilocatários.

   4. Clique em Continuar.

7. Para criar o provedor, clique em Enviar.

gcloud

Para configurar o provedor SAML usando a CLI gcloud, faça o seguinte:

  gcloud iam workforce-pools providers create-saml PROVIDER_ID \
      --workforce-pool=WORKFORCE_POOL_ID \
      --display-name="DISPLAY_NAME" \
      --description="DESCRIPTION" \
      --idp-metadata-path=METADATA_FILE_PATH \
      --attribute-mapping="ATTRIBUTE_MAPPING" \
      --attribute-condition="ATTRIBUTE_CONDITION" \
      --location=global

Substitua:

• PROVIDER_ID: o ID do provedor.
• WORKFORCE_POOL_ID: o ID do pool.
• DISPLAY_NAME é o nome de exibição do provedor. Por exemplo, idp-eu-employees.
• DESCRIPTION: a descrição do provedor de pool de identidade de colaboradores; por exemplo, IdP for Partner Example Organization EU employees.
• METADATA_FILE_PATH: o caminho do arquivo dos metadados SAML

• ATTRIBUTE_MAPPING: o mapeamento de atributo. Por exemplo:

  google.subject=assertion.subject,
  google.groups=assertion.attributes['https://example.com/aliases'],
  attribute.costcenter=assertion.attributes.costcenter[0]

  Este exemplo mapeia os atributos do IdP assertion.subject, assertion.attributes['https://example.com/aliases'] e assertion.attributes.costcenter[0] os atributos do Google Cloud google.subject, google.groups, e google.costcenter, respectivamente.

• ATTRIBUTE_CONDITION: uma condição de atributo. Por exemplo, para limitar o atributo ipaddr a um determinado intervalo de IP, defina a condição assertion.attributes.ipaddr.startsWith('98.11.12.'). Este exemplo de condição garante que apenas os usuários com um endereço IP que comece com 98.11.12. possam fazer login usando esse provedor de força de trabalho.

O provedor pode levar alguns minutos para começar a aceitar solicitações.

Para a federação SAML, você pode usar as seguintes palavras-chave em mapeamentos e condições de atributos:

• assertion.subject: uma string igual ao atributo NameID na declaração SAML.
• assertion.attributes.NAME: uma lista de strings igual aos valores dos atributos com nome semelhante na declaração SAML.

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 de colaboradores, faça isto:

• Na federação de identidade de colaboradores, faça isto:
• Crie um par de chaves assimétricas para seu provedor de pool de identidade de colaboradores.
• 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 de colaboradores.
• 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 de colaboradores ainda pode processar uma declaração de texto simples.

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

Nesta seção, mostramos como criar um par de chaves assimétricas que permite que a federação de identidade de colaboradores 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 workforce-pools providers keys create KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION

Substitua:

• KEY_ID: o nome da chave que você escolher
• WORKFORCE_POOL_ID: o ID do pool
• PROVIDER_ID: o ID do provedor
• 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 de colaboradores tem acesso à chave privada.

gcloud iam workforce-pools providers keys describe KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH

Substitua:

• KEY_ID: o nome da chave
• WORKFORCE_POOL_ID: o ID do pool
• PROVIDER_ID: o ID do provedor
• 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

Configure o IdP do SAML para que use o certificado público transferido por download na última etapa para criptografar as declarações SAML emitidas. Consulte a equipe do IdP para ter instruções específicas.

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 de colaboradores ainda pode processar declarações de texto simples.

Excluir chaves de criptografia da federação de identidade de colaboradores

Para excluir as chaves de criptografia SAML, execute o seguinte comando:

  gcloud iam workforce-pools providers keys delete KEY_ID \
      --workforce-pool WORKFORCE_POOL_ID \
      --provider PROVIDER_ID \
      --location global

Substitua:

• KEY_ID: o nome da chave
• WORKFORCE_POOL_ID: o ID do pool
• PROVIDER_ID: o ID do provedor

Algoritmos de criptografia SAML compatíveis

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

• http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
• http://www.w3.org/2009/xmlenc11#rsa-oaep"
• http://www.w3.org/2001/04/xmlenc#rsa-1_5"

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

• http://www.w3.org/2001/04/xmlenc#aes128-cbc
• http://www.w3.org/2001/04/xmlenc#aes192-cbc
• http://www.w3.org/2001/04/xmlenc#aes256-cbc
• http://www.w3.org/2009/xmlenc11#aes128-gcm
• http://www.w3.org/2009/xmlenc11#aes256-gcm

Requisitos da chave de assinatura SAML X.509

As especificações de chave a seguir se aplicam às chaves de assinatura SAML X.509:

• Uma chave pública RSA encapsulada em um certificado X.509 v3.

• Requisitos de validade do certificado:

  • notBefore: um carimbo de data/hora que não seja maior que sete dias no futuro
  • notAfter: um carimbo de data/hora que não seja mais de 20 anos no futuro

• Algoritmos recomendados:

  • RSAwithSHA256 (tamanhos de chave compatíveis (bits): 2048, 3072, 4096)
  • ECDSAwithSHA256

É possível configurar um provedor de pool de identidade de colaboradores com no máximo três chaves de assinatura por vez. Quando há várias chaves, o Google Cloud itera por elas e tenta usar cada chave não expirada para atender a uma solicitação de troca de token.

Como prática recomendada de segurança, recomendamos não reutilizar o mesmo par de chaves com outros serviços.

Gerenciamento de chaves

Importante: para garantir que o acesso dos usuários de colaboradores não seja interrompido quando as chaves expirarem, recomendamos que você as atualize regularmente. As chaves de assinatura pública usadas para validar assinaturas de declaração SAML têm uma data de validade. Após a data de validade, as chaves não poderão ser usadas para trocas de token.

Para atualizar as chaves de assinatura do IdP, faça o seguinte:

1. Crie um novo par de chaves assimétricas e configure o provedor de identidade SAML com o par de chaves. Inicialmente, você a marca como inativa antes de ativá-la em uma etapa posterior.

2. Faça o download de um documento XML de metadados SAML do IdP.

3. Atualize o recurso do provedor de pool de identidade de colaboradores usando o documento de metadados SAML. Quando há várias chaves, o Google Cloud faz a iteração em cada chave não vencida e tenta aplicá-la a uma solicitação de troca de token.

   Para atualizar o provedor de pool de identidade de colaboradores com os metadados SAML, execute o comando a seguir.

   gcloud iam workforce-pools providers update-saml PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --idp-metadata-path=SAML_METADATA_FILE_PATH \
       --location=global
   

   Substitua:

   • PROVIDER_ID: o ID do provedor
   • WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores
   • SAML_METADATA_FILE_PATH: o caminho para o arquivo de metadados SAML

4. Aguarde a conclusão da operação da etapa anterior (a operação é marcada como concluída) e, no IdP SAML, ative a nova chave de assinatura. A chave de assinatura antiga está marcada como inativa. As declarações emitidas pelo IdP são assinadas usando a nova chave.

As etapas a seguir são opcionais, mas recomendamos que você as execute como uma prática recomendada:

1. Exclua a chave de assinatura antiga, agora inativa, do IdP.
2. Faça o download do documento XML de metadados SAML no seu IdP.

3. Atualize o recurso do provedor de pool de identidade de colaboradores usando o documento de metadados SAML. O Google Cloud recusa declarações assinadas com a chave de assinatura expirada. Para atualizar a política, execute o seguinte comando:

   gcloud iam workforce-pools providers update-saml PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --idp-metadata-path=SAML_METADATA_FILE_PATH \
       --location=global
   

   Substitua:

   • PROVIDER_ID: o ID do provedor
   • WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores
   • SAML_METADATA_FILE_PATH: o caminho dos metadados SAML

Restrição de exclusão de chaves

O Google Cloud recusa declarações assinadas com uma chave excluída.

Cuidado: a exclusão acidental de uma chave que ainda está em uso pode causar interrupções. Só será possível atualizar um recurso do provedor de pool de identidade de colaboradores se os metadados SAML tiverem pelo menos uma chave de assinatura não expirada. Essa restrição será ignorada se todas as chaves de assinatura existentes expirarem.

Representar usuários do pool de forças de trabalho nas políticas do IAM

A tabela a seguir mostra os principais identificadores usados para conceder papéis a um único usuário, um grupo de usuários, aqueles que carregam uma declaração específica ou todos os usuários de um pool de forças de trabalho.

Observação: não é possível conceder o papel de proprietário (roles/owner) a um usuário de colaboradores em projetos.

Identidades	Formato do identificador
Identidade única em um pool de identidades de carga de trabalho	principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
Todas as identidades de força de trabalho em um grupo	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
Todas as identidades com um valor de atributo específico	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
Todas as identidades em um pool de Identidades de força de trabalho:	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*

Conceder papéis do IAM aos principais

É possível conceder papéis aos participantes, como identidades únicas, grupos de identidades ou um pool inteiro.

Para conceder um papel em um projeto a um principal, execute o seguinte comando:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="ROLE" \
    --member="PRINCIPAL"

Substitua:

• PROJECT_ID: o ID do projeto;
• ROLE: o papel a ser definido
• PRINCIPAL: o principal. Consulte Identificadores principais na Federação de identidade de colaboradores.

No exemplo a seguir, o comando concede o administrador do Storage (roles/storage.admin) a todas as identidades no grupo GROUP_ID:

gcloud projects add-iam-policy-binding my-project \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

Para mais informações sobre o formato principal, consulte Identificadores principais da Federação de identidade de colaboradores.

Excluir usuários

A federação de identidade de colaboradores cria metadados e recursos de usuários para identidades de usuários federadas. Se você optar por excluir usuários, no seu IdP, por exemplo, também será necessário excluir explicitamente esses recursos no Google Cloud. Para fazer isso, consulte Excluir usuários da federação de identidade de colaboradores e os dados deles.

Talvez você veja que os recursos continuam associados a um usuário que foi excluído. Isso ocorre porque a exclusão de metadados e recursos do usuário requer uma operação de longa duração. Depois de iniciar uma exclusão da identidade de um usuário, os processos que o usuário iniciou antes da exclusão podem continuar em execução até que sejam concluídos ou cancelados.

A seguir

• Conseguir credenciais de curta duração para a federação de identidade de colaboradores
• Gerenciar provedores de pools de identidade de colaboradores
• Excluir os usuários da federação de identidade de colaboradores e respectivos dados
• Saiba quais produtos do Google Cloud são compatíveis com a federação de identidade de colaboradores
• Configurar o acesso do usuário ao console (federado)