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

Este guia mostra como usar um pool de identidade da força de trabalho e um provedor de pool de força de trabalho 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 da força de trabalho a que você recebeu acesso.

Os métodos descritos neste guia podem ser usados em máquinas sem monitor.

É possível receber tokens de curta duração usando este processo de alto nível, descrito em detalhes mais adiante neste documento:

  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:

    Anote o ID do pool de identidade da força de trabalho e do provedor do pool de identidade da força de trabalho.

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

  3. Enable the IAM and Security Token Service APIs.

    Enable the APIs

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

    gcloud init

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 CLI gcloud usando a flag --activate. 

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

Substitua:

  • WORKFORCE_POOL_ID: o ID do pool de identidade da força de trabalho
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho
  • LOGIN_CONFIG_FILE: um caminho para o arquivo de configuração de login 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 IdP configurado no provedor do pool de identidade dos colaboradores. 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/WORKFORCE_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",
}

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

Quando você usa credenciais originadas de arquivos, 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/WORKFORCE_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 identidade da força de trabalho
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho
  • 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/WORKFORCE_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

Quando você usa 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 um arquivo de configuração com uma credencial de origem de URL, execute o seguinte comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identidade da força de trabalho.
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho.
  • 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/WORKFORCE_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

Quando você usa credenciais de origem executável não interativa, 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 é suportada.

  • 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 os seguintes 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 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: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 definem 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. Essa variável é sempre definida.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: o tipo de token de assunto esperado. Essa variável é sempre definida.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: o local do arquivo de saída da configuração da credencial. Essa variável só está presente quando especificada na configuração da 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/WORKFORCE_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 identidade da força de trabalho.
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho.
  • 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 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/WORKFORCE_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

Ao usar credenciais de origem executável interativas, você pode fornecer um executável que interage 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, as seguintes flags são necessárias:

  • --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 retorna os mesmos campos para credenciais interativas e não interativas de origem executável.

As variáveis de ambiente também são iguais para credenciais interativas e não interativas 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/WORKFORCE_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 identidade da força de trabalho.
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho.
  • 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 para as credenciais de terceiros geradas pelo executável. Esse caminho é útil para armazenar as credenciais em cache. As bibliotecas de autenticação 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/WORKFORCE_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",
    }
  }
}

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

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 ele completar uma hora.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identidade da força de trabalho.
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho.
  • 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](https://toolbox.googleapps.com/apps/encode_decode/) ou JSON contendo uma declaração SAML codificada em base64. Para usar credenciais originadas de URL, use a flag `--credential-source-url`: ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 o seguinte: * WORKFORCE_POOL_ID: o ID do pool de identidade da força de trabalho. * WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho. * CREDENTIAL_URL: o URL do endpoint do servidor local. * 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` 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 definem 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. Essa variável é sempre definida.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: o tipo de token de assunto esperado. Essa variável é sempre definida.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: o local do arquivo de saída da configuração da credencial. Essa variável só está presente quando especificada na configuração da credencial.

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/WORKFORCE_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 identidade da força de trabalho.
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho.
  • 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 para as credenciais de identidade de terceiros (3PI, na sigla em inglês) geradas pelo executável. Isso é útil para armazenar as credenciais em cache. As bibliotecas de autorização 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/WORKFORCE_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

Quando você usa credenciais de origem executável para o modo interativo da gcloud, um executável interage com o usuário pela interface de 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. Quando expiration_time é omitido, o executável ainda é executado.

O executável precisa mostrar todos os erros para executable-output-file no seguinte formato JSON. Quando o executável informa um erro, esses campos são obrigatórios. Os campos de código e mensagem são usados pelas bibliotecas de cliente ao gerar o erro apropriado.

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

A execução bem-sucedida do comando retorna os mesmos campos das credenciais de origem executável não interativas.

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

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/WORKFORCE_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 identidade da força de trabalho.
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho.
  • 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: uma duração, em milissegundos, para aguardar a execução do executável.
  • EXECUTABLE_OUTPUT_FILE: um caminho para as credenciais de terceiros geradas pelo executável. Isso é útil para armazenar as credenciais em cache. As bibliotecas de autenticação 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 do IdP SAML semelhante a este:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>WORKFORCE_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>",
    }
  }
}

Para fazer login, execute este comando:

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

Nem a CLI gcloud nem a ferramenta de linha de comando bq são compatíveis com tipos de credenciais de origem executável.

Para fluxos sem cabeça, a CLI gcloud usa automaticamente o seguinte escopo: https://www.googleapis.com/auth/cloud-platform. A CLI gcloud posta as credenciais de forma transparente 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:

Ferramenta 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 da força de trabalho na ferramenta bq está disponível na versão 390.0.0 e posteriores da Google Cloud CLI.

C++

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

As bibliotecas de cliente do Cloud Storage para C++ usam a API REST, não o gRPC, portanto, elas não são compatíveis com a federação de identidade da força de trabalho.

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

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

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

Go

As bibliotecas de cliente do Cloud para Go são compatíveis com a federação de identidade da força de trabalho quando você usa 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 do Cloud para Java oferecem suporte à federação de identidade da força de trabalho quando você usa 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 do Cloud para Node.js são compatíveis com a federação de identidade da força de trabalho quando você usa 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 identidade da força 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 do 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 do Cloud para Python são compatíveis com a federação de identidade da força de trabalho quando você usa a versão 2.3.0 ou mais recente 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 código de exemplo, o valor project pode ser None se a biblioteca não conseguir descobrir automaticamente o ID do projeto. É possível transmitir o ID do projeto explicitamente ao usar uma instância de serviço, como no exemplo do cliente de armazenamento, ou definir o ID do projeto pela 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 executando o seguinte comando:

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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.
  • WORKFORCE_POOL_ID: o ID do pool de identidade da força de trabalho
  • WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade da força de trabalho

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

    Se você tiver configurado um provedor OIDC, o token precisa estar formatado em JWT.

  • BILLING_PROJECT_NUMBER: o número ou o ID do projeto usado para a cota e o faturamento. O principal precisa definir 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 a CLI 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, a CLI gcloud inspeciona o arquivo de credenciais fornecido e verifica a validade das credenciais recebidas do IdP. Se as credenciais ainda forem válidas, a CLI gcloud vai 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 conferir 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
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

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