Receber tokens de curta duração para a federação de identidade de colaboradores

Este guia mostra como usar um pool de identidade de colaboradores e um provedor de pool de identidade de colaboradores para receber tokens de curta duração do Security Token Service. É possível usar os tokens para acessar os recursos do Google Cloud compatíveis com a federação de identidade de colaboradores e a que você recebeu acesso.

Observação: o procedimento descrito neste guia pode ser usado em máquinas headless.

Você consegue tokens de curta duração seguindo este processo:

1. Consiga uma credencial do provedor de identidade confiável.
2. Troque a credencial por um token do Security Token Service.

Antes de começar

1. Configure a federação de identidade de colaboradores ou, para instruções específicas do IdP, consulte os seguintes guias:

   • 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

2. Você precisa saber o código do pool de funcionários ou do provedor.

3. Verifique se você tem a permissão serviceusage.services.use do Identity and Access Management (IAM). O papel menos privilegiado que contém essa permissão é o consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer).

4. Enable the IAM and Security Token Service APIs.

   Enable the APIs

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

Trocar credenciais externas por um token de acesso do Google Cloud

Nesta seção, mostramos como usar o Serviço de token de segurança para trocar suas credenciais externas por um token de acesso que concede acesso ao Google Cloud. Para fazer isso, use a CLI gcloud, a API REST e as bibliotecas de cliente do Cloud, conforme descrito mais adiante neste guia.

Se você precisar de acesso de longa duração, poderá configurar um processo de longa duração para atualizar continuamente as credenciais nessa máquina. Como alternativa, é possível executar um servidor local em segundo plano com um endpoint que retorna as credenciais.

Login baseado no navegador com a CLI gcloud

Nesta seção, descrevemos como configurar a CLI gcloud para usar um fluxo de login baseado em navegador. Para fazer isso, crie um arquivo de configuração de login e o referencie em chamadas para gcloud auth login ou ative-o para que seja usado por padrão.

Criar o arquivo de configuração de login

Para criar o arquivo de configuração de login, execute o comando a seguir. Também é possível ativar o arquivo como padrão para a gcloud CLI usando a flag --activate.

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores
• PROVIDER_ID: o ID do provedor
• LOGIN_CONFIG_FILE: um caminho para o arquivo de configuração especificado. Por exemplo, login.json.

O arquivo contém os endpoints usados pela CLI gcloud para ativar o fluxo de autenticação baseado em navegador e definir o público como o provedor criado anteriormente neste guia. O arquivo não contém informações confidenciais.

A saída será assim:

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

Atenção: recomendamos que você confira se o conteúdo do arquivo está correto e depois o proteja. Por exemplo, torne-o somente leitura e restrinja o acesso com uma ACL. O arquivo não foi validado. Uma pessoa mal-intencionada com acesso de gravação a este arquivo pode alterar os endpoints e interceptar as credenciais.

Fazer login usando autenticação baseada no navegador

Para usar a autenticação de login baseada em navegador, use um dos seguintes métodos:

• Se você usou a flag --activate ao criar o arquivo de configuração ou ativou esse arquivo com gcloud config set auth/LOGIN_CONFIG_FILE, a gcloud CLI fará uso dele automaticamente:

  gcloud auth login

• Para fazer login especificando o local do arquivo de configuração, execute o seguinte comando:

  gcloud auth login --login-config=LOGIN_CONFIG_FILE

• Para usar uma variável de ambiente para especificar o local do arquivo de configuração, defina CLOUDSDK_AUTH_LOGIN_CONFIG_FILE como o caminho de configuração.

Desativar o login baseado no navegador

Para interromper o uso do arquivo de configuração de login, faça o seguinte:

• Se você usou a flag --activate ao criar o arquivo de configuração ou ativou esse arquivo com gcloud config set auth/LOGIN_CONFIG_FILE, execute o seguinte comando para cancelar a definição:

  gcloud config unset auth/login_config_file

• Limpe a variável de ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, se ela estiver definida.

Usar arquivos de configuração para login

Como alternativa ao login baseado em navegador, nesta seção, mostramos diferentes maneiras de usar arquivos de configuração de credencial para fornecer acesso a ações autenticadas do Google Cloud. Não é necessário fazer login na gcloud CLI para definir os arquivos de configuração.

O modo de definição do arquivo de configuração depende do que o IdP usa: OIDC ou SAML.

OIDC

É possível encontrar as credenciais usadas para definir o arquivo de configuração nas seguintes fontes:

• Credenciais fornecidas pelo arquivo
• Credenciais fornecidas pelo URL
• Credenciais não interativas de origem executável
• Credenciais interativas de origem executável

Credenciais fornecidas pelo arquivo

Os tokens são carregados de um arquivo. Outro processo precisa atualizar esse arquivo com um novo token OIDC antes que o antigo expire. Por exemplo, se o token tiver um ciclo de vida de uma hora, você precisará atualizar o arquivo antes de ele completar uma hora.

Para gerar o arquivo de configuração com uma credencial gerada por arquivo, execute o seguinte comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores
• PROVIDER_ID: o ID do provedor
• PATH_TO_OIDC_TOKEN: o caminho para o arquivo de credencial do IdP OIDC
• WORKFORCE_POOL_USER_PROJECT: o número ou o ID do projeto associado ao projeto do usuário dos pools de colaboradores.

O principal precisa ter a permissão serviceusage.services.use neste projeto.

A execução do comando produz um arquivo de configuração de IdP do OIDC semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

Credenciais fornecidas pelo URL

Os tokens são carregados de um servidor local com um endpoint que responde a solicitações HTTP GET. A resposta precisa ser um token de ID do OIDC, em texto simples ou em formato JSON.

Para gerar o arquivo de configuração com uma credencial fornecida por URL, execute o seguinte comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• URL_TO_RETURN_OIDC_ID_TOKEN: o URL a ser chamado para recuperar as credenciais do OIDC, como um token de ID do OIDC, por exemplo: http://localhost:5000/token.
• WORKFORCE_POOL_USER_PROJECT: o número do projeto usado para a cota e o faturamento. O principal precisa ter serviceusage.services.use permission neste projeto.

A execução do comando produz um arquivo de configuração de IdP do OIDC semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Credenciais não interativas de origem executável

Os tokens são carregados de um executável local. O executável precisa fornecer um token de ID do OIDC válido e não expirado no formato JSON para stdout:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Esses campos são obrigatórios para uma resposta bem-sucedida, exceto expiration_time. O campo expiration_time só é necessário quando um arquivo de saída é especificado na configuração da credencial.

O executável precisa exibir todos os erros para stdout no seguinte formato JSON:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos esses campos são obrigatórios para uma resposta de erro. Os campos de código e mensagem são usados pelas bibliotecas de cliente para levantar o erro apropriado.

O comando pode retornar os seguintes campos:

• version: a versão da saída JSON. Apenas a versão 1 é compatível.

• success: o status da resposta. Quando o status é true, o executável precisa sair com o código de saída 0, e a resposta precisa conter estes campos:

  • token_type: id_token
  • Campo expiration_time se um arquivo de saída tiver sido especificado na configuração da credencial.

  Quando o status é false, o executável precisa sair com um valor diferente de zero, e a resposta precisa ter os seguintes campos:

  • code
  • message

• token_type: o tipo de token de assunto de terceiros, que precisa ser urn:ietf:params:oauth:token-type:id_token

• id_token: o token OIDC de terceiros

• expiration_time: o prazo de validade do token OIDC de terceiros em segundos (horário de época do Unix)

• code: a string do código de erro

• message: a mensagem de erro

As bibliotecas de cliente preenchem as seguintes variáveis de ambiente quando o executável é executado:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: o campo de público-alvo da configuração da credencial. Sempre presente.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: o tipo de token de assunto esperado. Sempre presente.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: o local do arquivo de saída da configuração da credencial. Presente apenas quando especificado na configuração de credencial.

Essas variáveis de ambiente podem ser usadas pelo executável para evitar que esses valores sejam fixados no código.

Para ativar esse método de geração de credenciais com as bibliotecas de cliente, a variável de ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES precisa ser definida como 1.

Para gerar o arquivo de configuração com uma credencial de origem executável, execute o seguinte comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• EXECUTABLE_COMMAND: o comando completo, incluindo argumentos, a ser executado para recuperar o token do assunto, como um token de ID do OIDC, no seguinte formato: --executable-command="/path/to/command --foo=bar".
• EXECUTABLE_TIMEOUT: (opcional) uma duração, em milissegundos, para aguardar a execução do executável (o padrão é 30s).
• EXECUTABLE_OUTPUT_FILE: (opcional) um caminho de arquivo para as credenciais de terceiros geradas pelo executável. Isso é útil para armazenar as credenciais em cache. As bibliotecas do Auth verificam esse caminho antes de executar o executável.
• WORKFORCE_POOL_USER_PROJECT: o número ou o ID do projeto usado para cota e faturamento. O principal precisa ter a permissão serviceusage.services.use definida neste projeto.

A execução do comando produz um arquivo de configuração de IdP do OIDC semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Credenciais interativas de origem executável

É possível fornecer um executável que interaja com o usuário usando stdin e stdout. Se o usuário fizer login, o executável gravará uma credencial válida e não expirada no arquivo especificado.

Para usar esse modo, os seguintes flags são necessários:

• --executable-output-file: o arquivo em que o executável grava as informações da credencial.
• --exeutable-interactive-timeout-millis: um valor diferente de zero que indica o modo interativo e define o tempo limite. Por exemplo, 6000 para um tempo limite de 60 segundos.

Os campos a seguir são obrigatórios para uma resposta bem-sucedida, exceto expiration_time:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

O executável precisa gravar erros no arquivo especificado em --executable-output-file no seguinte formato JSON. Todos os campos a seguir são obrigatórios para retornar uma resposta de erro.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Os campos code e message precisam indicar o erro apropriado. Esses campos são usados pelas bibliotecas de cliente ao gerar o erro.

Após a execução bem-sucedida, o comando retornará os mesmos campos, independentemente de você usar os resultados das credenciais interativas ou não interativas de origem executável acima.

As variáveis de ambiente também são iguais às credenciais normais de origem executável.

Para gerar uma credencial interativa de origem executável, adicione o parâmetro --executable-interactive-timeout-millis e o parâmetro --executable-output-file.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• EXECUTABLE_COMMAND: o comando completo, incluindo argumentos, a ser executado para recuperar o token do assunto, formatado da seguinte maneira: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
• EXECUTABLE_INTERACTIVE_TIMEOUT: uma duração, em milissegundos, para aguardar a execução do executável.
• EXECUTABLE_OUTPUT_FILE: um caminho de arquivo para as credenciais de terceiros geradas pelo executável. Esse caminho é útil para armazenar as credenciais em cache. As bibliotecas do Auth verificam esse caminho antes de executar o executável.
• WORKFORCE_POOL_USER_PROJECT: o número ou o ID do projeto usado para cota e faturamento O principal precisa definir a permissão serviceusage.services.use neste projeto.

A execução do comando produz um arquivo de configuração de IdP do OIDC semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

Observação: o campo timeout_millis é retornado porque um executável interativo também pode ser executado no modo não interativo em alguns casos. No modo interativo, o comando retorna um tempo limite padrão.

SAML

É possível encontrar as credenciais usadas para definir o arquivo de configuração nas seguintes fontes:

• Credenciais fornecidas pelo arquivo
• Credenciais fornecidas pelo URL
• Credenciais de origem executáveis
• Credenciais de origem executável para o modo interativo da gcloud

Credenciais fornecidas pelo arquivo

As declarações são carregadas de um arquivo. Outro processo precisa atualizar esse arquivo com uma nova declaração SAML codificada em base64 antes que a antiga expire. Por exemplo, se a declaração tiver um ciclo de vida de uma hora, você precisará atualizar o arquivo antes de ela completar uma hora.

Observação: é necessário transmitir uma flag --subject-token-type=urn:ietf:params:oauth:token-type:saml2 ao gerar o arquivo de configuração.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• CREDENTIAL_FILE: o caminho para o arquivo de credencial gerado pelo IdP.
• WORKFORCE_POOL_USER_PROJECT: o número ou o ID do projeto usado para cota e faturamento. O principal precisa ter serviceusage.services.use permission neste projeto.

Credenciais fornecidas pelo URL

As declarações são carregadas de um servidor local com um endpoint que responde a solicitações HTTP GET. A resposta precisa ser uma declaração SAML codificada em base64 ou JSON contendo uma declaração SAML codificada em base64.

Para usar credenciais originadas de URL, use a flag --credential-source-url:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-url=CREDENTIAL_URL \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• CREDENTIAL_URL: o URL do endpoint do servidor local.
• WORKFORCE_POOL_USER_PROJECT: o ID ou o número do projeto usado para a cota e o faturamento. O principal precisa ter serviceusage.services.use permission neste projeto.

Credenciais de origem executáveis

As declarações são carregadas de um executável local. O executável precisa fornecer uma declaração SAML válida e não expirada no formato JSON para stdout.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Esses campos são obrigatórios para uma resposta bem-sucedida, exceto expiration_time. O campo expiration_time é obrigatório somente quando um arquivo de saída é especificado na configuração da credencial.

Se ocorrer um erro, ele precisará ser exibido pelo executável no seguinte formato JSON para stdout:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos esses campos são obrigatórios para uma resposta de erro. Os campos de código e mensagem são usados pelas bibliotecas de cliente para levantar o erro apropriado.

O comando pode retornar os seguintes campos:

• version: a versão da saída JSON. Apenas a versão 1 é suportada.

• success: o status da resposta. Quando o status é true, o executável precisa ser encerrado com o código de saída 0, e a resposta precisa conter estes campos:

  • token_type: saml_response
  • Campo expiration_time se um arquivo de saída tiver sido especificado na configuração da credencial

  Quando o status é false, o executável precisa sair com um valor diferente de zero, e a resposta precisa conter os seguintes campos: + code + message

• token_type: o tipo de token de assunto de terceiros, que precisa ser urn:ietf:params:oauth:token-type:saml2

• saml_response: a resposta SAML de terceiros

• expiration_time: o prazo de validade da resposta SAML de terceiros em segundos (horário da época Unix)

• code: a string do código de erro

• message: a mensagem de erro

As bibliotecas de cliente preenchem as seguintes variáveis de ambiente quando o executável é executado:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: o campo de público-alvo da configuração da credencial. Sempre presente.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: o tipo de token de assunto esperado. Sempre presente.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: o local do arquivo de saída da configuração da credencial. Presente apenas quando especificado na configuração da credencial.

Observação: o executável pode usar essas variáveis de ambiente para evitar a fixação desses valores no código.

Para ativar esse método de geração de credenciais com as bibliotecas de cliente, defina a variável de ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES como 1.

Para gerar o arquivo de configuração com uma credencial de origem executável, execute o seguinte comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• EXECUTABLE_COMMAND: o comando completo, incluindo argumentos, a ser executado para recuperar o token do assunto, no seguinte formato: --executable-command="/path/to/command --foo=bar".
• EXECUTABLE_TIMEOUT: (opcional) a duração, em milissegundos, para aguardar a execução do executável (o padrão é 30s).
• EXECUTABLE_OUTPUT_FILE: (opcional) o caminho do arquivo para as credenciais de 3PI geradas pelo executável. Isso é útil para armazenar as credenciais em cache. As bibliotecas do Auth verificam a existência dele antes de executar o executável.
• WORKFORCE_POOL_USER_PROJECT: o número do projeto usado para a cota e o faturamento. O principal precisa definir a permissão serviceusage.services.use neste projeto.

A execução do comando produz um arquivo de configuração do IdP SAML semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Credenciais de origem executável para o modo interativo da gcloud

Um executável interage com o usuário pela linha de comando.

No comando anterior, substitua o seguinte:

• EXECUTABLE_OUTPUT_FILE: (obrigatório) o caminho para o arquivo que fornece as credenciais geradas pelo executável.
• EXECUTABLE_TIMEOUT: (obrigatório) um valor de tempo limite diferente de zero também sinaliza o comando para usar o modo interativo.

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

Esses campos são obrigatórios para uma resposta bem-sucedida, exceto expiration_time. O valor expiration_time ausente será tratado como um indicador de que o executável será executado de qualquer forma.

O executável precisa exibir todos os erros para executable-output-file no seguinte formato JSON:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos esses campos são obrigatórios para uma resposta de erro. Os campos de código e mensagem são usados pelas bibliotecas de cliente para levantar o erro apropriado.

Os campos de retorno de comando para uma execução de sucesso são exatamente os mesmos com os resultados de credenciais de origem executável normais acima.

As variáveis de ambiente também são iguais às credenciais normais de origem executável.

Para gerar uma credencial interativa de origem executável, adicione o parâmetro --executable-interactive-timeout-millis.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores.
• PROVIDER_ID: o ID do provedor.
• EXECUTABLE_COMMAND: o comando completo, incluindo argumentos, a ser executado para recuperar o token do assunto, formatado da seguinte maneira: --executable-command="/path/to/command --foo=bar").
• EXECUTABLE_INTERACTIVE_TIMEOUT: a duração, em milissegundos, para aguardar a execução do executável.
• EXECUTABLE_OUTPUT_FILE: um caminho de arquivo para as credenciais de terceiros geradas pelo executável. Isso é útil para armazenar as credenciais em cache. As bibliotecas do Auth verificam esse caminho antes de executar o executável.
• WORKFORCE_POOL_USER_PROJECT: o número ou o ID do projeto usado para cota e faturamento O principal definiu a permissão serviceusage.services.use neste projeto.

A execução do comando produz um arquivo de configuração do IdP SAML semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

Observação: timeout_millis está incluído na configuração porque uma credencial interativa de origem executável também pode ser executada no modo não interativo em alguns casos. O gerador de configuração da CLI gcloud preenche automaticamente esse campo com a configuração de tempo limite padrão de 30 segundos.

Para fazer login, execute este comando:

gcloud auth login --cred-file=/path/to/config.json

As CLIs (gcloud, bq) não são compatíveis com tipos de credenciais de origem executável.

Para fluxos headless, gcloud usa automaticamente o seguinte escopo: https://www.googleapis.com/auth/cloud-platform. Em seguida, o gcloud posta de maneira transparente as credenciais no endpoint do serviço de token de segurança, em que ele é trocado por tokens de acesso temporários do Google Cloud.

Agora é possível executar comandos gcloud usando a CLI gcloud.

Usar as bibliotecas de cliente do Google Cloud

Se você usa uma biblioteca de cliente compatível, pode configurá-la para que ela gere credenciais do Google automaticamente. Quando possível, recomendamos que você gere credenciais automaticamente para não precisar implementar o processo de troca de token por conta própria.

A biblioteca de cliente do Google Cloud é compatível com pools de forças de trabalho nas seguintes linguagens: Node.js, Java, Python, Go e C++ (gRPC).

Para usar bibliotecas de cliente com esses serviços ou linguagens, faça o seguinte:

bq

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

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

em que FILEPATH é o caminho relativo do arquivo de configuração de credenciais.

O suporte para a federação de identidade de colaboradores na bq está disponível na versão 390.0.0 e posteriores da CLI do Google Cloud.

C++

A maioria das bibliotecas de cliente do Google Cloud para C++ é compatível com a federação de identidade de colaboradores usando um objeto ChannelCredentials, que é criado chamando grpc::GoogleDefaultCredentials(). Para inicializar essa credencial, crie as bibliotecas de cliente com a versão 1.42.0 ou posteriores do gRPC.

A biblioteca de cliente do Cloud Storage para C++ usa a API REST, não o gRPC, portanto, ela não é compatível com a federação de identidade de colaboradores.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

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

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

em que FILEPATH é o caminho relativo do arquivo de configuração de credenciais.

O suporte à federação de identidade de colaboradores em gcloud está disponível na versão 392.0.0 e posteriores da CLI do Google Cloud.

Go

As bibliotecas de cliente para Go aceitam a federação de identidade de colaboradores se elas usarem a versão v0.0.0-20211005180243-6b3c2da341f1 ou mais recente do módulo golang.org/x/oauth2.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

Java

As bibliotecas de cliente para Java oferecem suporte à federação de identidade de colaboradores, caso elas usem a versão 1.2.0 ou mais recente do artefato com.google.auth:google-auth-library-oauth2-http.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

As bibliotecas de cliente para Node.js são compatíveis com a federação de identidade de colaboradores. Você precisa usar a versão 7.10.0 ou mais recente do pacote google-auth-library. Ao contrário dos pools de identidade de colaboradores, os pools de forças de trabalho são associados a uma organização, não a um projeto do Google Cloud. Ao criar um objeto GoogleAuth, você precisa especificar um ID de projeto. Para mais informações, consulte o README do pacote google-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

As bibliotecas de cliente para Python são compatíveis com a federação de identidade de colaboradores se usarem a versão 2.3.0 ou posterior do pacote google-auth.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

No exemplo acima, o valor project poderá ser None se a biblioteca não puder descobrir isso automaticamente. É possível transmiti-la explicitamente ao usar uma instância de serviço (como no exemplo do cliente de armazenamento) ou defini-la por meio da variável de ambiente GOOGLE_CLOUD_PROJECT.

Para ver detalhes, consulte o guia do usuário do pacote google-auth.

Usar a API REST

É possível chamar a API Google Cloud Security Token para trocar suas credenciais externas por tokens de acesso do Google Cloud.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

Substitua:

• AUDIENCE: o nome do recurso completo do provedor que emite o token do assunto.
• PROVIDER_ID: o ID do provedor

• Defina como um dos seguintes: SUBJECT_TOKEN_TYPE

  • urn:ietf:params:oauth:token-type:id_token para tokens de ID do OIDC
  • urn:ietf:params:oauth:token-type:saml2 para declarações SAML

• EXTERNAL_SUBJECT_TOKEN: o token emitido pelo IdP que representa a identidade do principal para quem o token de acesso é solicitado. Observação: se você usa OIDC, o token está formatado em JWT.

• BILLING_PROJECT_NUMBER: o ID ou o número do projeto usado para a cota e o faturamento. O principal precisa ter a permissão serviceusage.services.use neste projeto.

A resposta é semelhante a:

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Gerenciar sessões usando a CLI gcloud

Os tokens temporários do Google Cloud que gcloud recebe do endpoint do serviço de token de segurança expiram após um intervalo de tempo especificado. Quando o token está prestes a expirar, o gcloud inspeciona o arquivo de credenciais fornecido e verifica a validade das credenciais recebidas do IdP. Se as credenciais ainda forem válidas, a gcloud buscará de maneira transparente um novo token de acesso do Google Cloud, e a sessão atual será executada sem interrupções.

Se suas credenciais expirarem, nenhum novo token do Google Cloud será emitido, e todas as chamadas feitas com essas credenciais falharão. Nesse momento, você precisará se autenticar novamente.

É possível encerrar a sessão executando o seguinte comando:

gcloud auth revoke

O gcloud é compatível com várias sessões de usuário. Para ver a lista de sessões, incluindo a que está ativa no momento, execute o seguinte comando:

gcloud auth list

A saída deste comando é semelhante a:

Credentialed Accounts
ACTIVE    ACCOUNT
*         [e-mail]
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/[e-mail]

Para mudar para uma sessão diferente e defini-la como ativa, execute o seguinte comando:

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

A seguir

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