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

É possível 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 ou da API Cloud OAuth. Com esses tokens, é possível acessar os recursos do Google Cloud que oferecem suporte à federação de identidade de colaboradores e para os quais você tem permissões.

É possível usar os métodos descritos neste documento em máquinas headless.

Para conseguir tokens de curta duração, siga este processo geral:

  1. Consiga uma credencial do provedor de identidade (IdP) confiável ou redirecione os usuários para o endpoint de autorização (https://auth.cloud.google/authorize) para fazer login com o IdP e receber um código de autorização.
  2. Troque a credencial ou o código de autorização por um token do Security Token Service ou da API Cloud OAuth.

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 identidades de colaboradores e o ID do provedor do pool de identidades de colaboradores.

  2. Verifique se todos os principais que trocam tokens usando o Security Token Service têm 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. Ative as APIs do IAM, do Serviço de token de segurança e da API Cloud OAuth, se ainda não estiverem ativadas.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  4. Instale a CLI do Google Cloud. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Trocar credenciais externas por um token de acesso do Google Cloud

Nesta seção, mostramos como usar o Security Token Service ou a API Cloud OAuth 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 documento.

Para instruções sobre como receber um código de autorização do endpoint de autorização (https://auth.cloud.google/authorize) e trocar códigos de autorização e tokens de atualização usando a API Cloud OAuth, consulte Trocar tokens com a API Cloud OAuth.

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

Execute o seguinte comando para criar um arquivo de configuração de login:

Linux e macOS

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

Windows (PowerShell)

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

Substitua:

  • WORKFORCE_POOL_ID: o ID do pool de federação de identidade de colaboradores.
  • WORKFORCE_PROVIDER_ID: o ID do provedor da federação de identidade de colaboradores.
  • LOGIN_CONFIG_PATH: o caminho para gravar o arquivo de configuração de login. Por exemplo, login-config.json.

O arquivo de configuração de login contém os endpoints usados pela CLI gcloud para ativar o fluxo de autenticação baseado em navegador e definir o público-alvo como o IdP que foi configurado no provedor do pool de identidades de colaboradores. O arquivo não contém informações confidenciais.

O conteúdo do arquivo de configuração de login é semelhante ao seguinte:

{
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "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

Aponte para o arquivo de configuração de login com uma variável de ambiente, uma propriedade na configuração ativa da CLI gcloud ou use-o diretamente com o comando gcloud auth login:

Variável de ambiente

Para usar o arquivo de configuração de login com uma variável de ambiente, siga estas instruções:

  1. Defina a variável de ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE como o caminho do arquivo de configuração de login.

  2. Execute este comando:

    gcloud auth login
  3. A CLI gcloud faz referência à variável de ambiente para encontrar o arquivo de configuração de login e, em seguida, inicia o processo de autenticação. Siga o fluxo baseado em navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.

Para interromper o uso do arquivo de configuração de login para comandos gcloud auth login, limpe a variável de ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

Configuração da CLI gcloud

Para usar o arquivo de configuração de login com uma propriedade de configuração da CLI gcloud, siga estas instruções:

  1. Defina a propriedade auth/login_config_file da configuração ativa da CLI gcloud como o caminho do arquivo de configuração de login com o seguinte comando: 

    gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

  2. Execute este comando:

    gcloud auth login
  3. A CLI gcloud faz referência à propriedade de configuração para encontrar o arquivo de configuração de login e, em seguida, inicia o processo de autenticação. Siga o fluxo baseado em navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.

Para interromper o uso do arquivo de configuração de login para comandos gcloud auth login, remova a definição da propriedade com o seguinte comando: 

gcloud config unset auth/login_config_file

gcloud auth login

Para usar o arquivo de configuração de login diretamente com o comando gcloud auth login, siga estas instruções:

  • Se você usou a flag --activate ao criar o arquivo de configuração de login, execute o seguinte comando: 

    gcloud auth login

  • Se você não usou a flag --activate ao criar o arquivo de configuração de login, execute o seguinte comando:

    Linux e macOS

    gcloud auth login \
    --login-config=LOGIN_CONFIG_PATH

    Windows (PowerShell)

    gcloud auth login `
    --login-config=LOGIN_CONFIG_PATH

    Substitua LOGIN_CONFIG_PATH pelo caminho do arquivo de configuração de login.

O comando gcloud auth login armazena as credenciais de acesso no diretório principal. O principal autenticado se torna o principal ativo na configuração ativa da CLI gcloud. A menos que sejam substituídas, a CLI gcloud usa essas credenciais armazenadas para acessar o Google Cloud.

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 doGoogle Cloud . Não é necessário fazer login na CLI gcloud 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 originárias do 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/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 fornecida por 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 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": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Credenciais não interativas de origem executável

Quando você usa 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 é 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: 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 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.

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 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, 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, 60000 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 para credenciais interativas e não interativas de origem executável.

As variáveis de ambiente também são as mesmas 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 ela 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 a permissão serviceusage.services.use 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: * WORKFORCE_POOL_ID: o ID do pool de identidades de colaboradores. * WORKFORCE_PROVIDER_ID: o ID do provedor do pool de identidade de colaboradores. * 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) 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 exibir todos os erros para executable-output-file no seguinte formato JSON. Quando o executável relata um erro, todos esses campos são obrigatórios. Os campos de código e mensagem são usados pelas bibliotecas de cliente para levantar o erro apropriado.

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

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

As variáveis de ambiente também são iguais às credenciais não interativas 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/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

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

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

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.

As bibliotecas de cliente doGoogle Cloud são compatíveis com pools de colaboradores 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 de colaboradores 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 doGoogle 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 mais recente 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 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

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

O suporte à federação de identidade de colaboradores 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 de colaboradores quando você usa a versão v0.0.0-20211005180243-6b3c2da341f1 ou posterior 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 são compatíveis com a federação de identidade de colaboradores quando você usa a versão 1.2.0 ou posterior 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 de colaboradores 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 carga de trabalho, os pools de identidade de colaboradores 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 de colaboradores quando você usa 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 código de exemplo, o valor project poderá ser None se a biblioteca não puder 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 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

Para receber um código de autorização do endpoint de autorização (https://auth.cloud.google/authorize) e trocar códigos de autorização ou tokens de atualização usando a API Cloud OAuth (cloudoauth.googleapis.com), consulte Trocar tokens com a API Cloud OAuth.

Também é possível chamar a API Security Token Service do Google Cloud 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ê configurou 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.

O resultado parecido com este:

{
  "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 Google Cloud que a CLI gcloud recebe do endpoint do Security Token Service 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 buscará de maneira transparente um novo token de acesso doGoogle 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
Para revogar todas as sessões ativas e credenciais de curta duração de um usuário do pool de colaboradores em todos os clientes como administrador, siga as instruções em Revogar sessões de usuário da federação de identidade de colaboradores.

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