Autenticar para a CLI gcloud

Este documento trata apenas da autenticação da Google Cloud CLI para acessar recursos.Google Cloud Se você precisar autenticar cargas de trabalho usando as bibliotecas de cliente do Cloud ou as bibliotecas de cliente de APIs do Google, consulte Como funcionam as Application Default Credentials.

Antes de começar

Se você não conhece o Google Cloud e quer começar a usar comandos da CLI gcloud no seu ambiente de desenvolvimento local, inicialize a CLI gcloud com o comando a seguir:

gcloud init

A inicialização orienta você por um fluxo de autenticação, configura uma configuração da CLI gcloud e autoriza a CLI gcloud a agir em seu nome. Não é necessário realizar uma etapa de autenticação separada.

O restante deste documento aborda cenários mais complexos, como usar a CLI gcloud com diferentes tipos de principais, métodos de autenticação adequados para diferentes ambientes, troca de principais e gerenciamento de credenciais armazenadas.

Métodos de autenticação

Todos os comandos da CLI gcloud precisam ser autenticados nas APIs Google Cloud. É possível fazer a autenticação das seguintes maneiras:

  • Autorizar e armazenar credenciais: adequado para uso humano em um ambiente de desenvolvimento local. É possível autorizar a CLI gcloud a agir em nome de um principal usando o comando gcloud auth login. Após a autenticação inicial, esse comando armazena as credenciais no diretório de configuração da CLI gcloud. A CLI gcloud usa essas credenciais armazenadas para autenticar automaticamente os comandos subsequentes até que sua sessão expire ou você revogue a autorização.

  • Autenticar com um arquivo de credenciais: adequado para cargas de trabalho executadas fora do Google Cloud. É possível usar variáveis de ambiente ou propriedades de configuração da CLI gcloud para especificar um arquivo de credenciais para autenticação automática. Esse arquivo pode ser um dos seguintes:

    • Um arquivo de configuração de credenciais da federação de identidade da carga de trabalho.

    • Uma chave de conta de serviço.

  • Forneça um token de acesso: adequado para fluxos de trabalho automatizados altamente isolados ou sessões sem estado em máquinas compartilhadas. É possível ignorar o armazenamento de credenciais fornecendo um token de acesso diretamente para a CLI gcloud. Para isso, defina uma variável de ambiente específica como a string do token de acesso bruto ou faça com que a CLI gcloud aponte para um arquivo que contenha o token de acesso.

Depois da autenticação, você pode permitir que a CLI gcloud represente uma conta de serviço fornecendo o endereço de e-mail dela.

É possível usar vários métodos de autenticação em um único ambiente. No entanto, apenas um principal é usado para qualquer comando gcloud. Para determinar qual principal usar, a CLI gcloud segue uma ordem de prioridade.

Quando não é necessário autenticar

Não é necessário autenticar a CLI gcloud nas seguintes situações:

  • Imediatamente depois de inicializar a CLI gcloud. A autenticação e a autorização estão incluídas no processo de inicialização. Talvez seja necessário autenticar novamente se você precisar acessar recursos diferentes usando um principal diferente ou se precisar autenticar novamente seu principal.
  • Ao usar a CLI gcloud de um recurso que expõe um servidor de metadados do Compute Engine. Isso inclui recursos como instâncias de VM do Compute Engine, serviços do Cloud Run e builds do Cloud Build. A CLI gcloud faz a autenticação usando a conta de serviço anexada à VM e está autorizada a acessar os mesmos recursos que essa conta de serviço dentro dos limites de qualquer escopo de acesso aplicado.
  • Ao usar o Cloud Shell. A CLI gcloud faz a autenticação automaticamente usando o principal com que você fez login no console Google Cloud . Quando você executa um comando da CLI gcloud pela primeira vez em uma nova sessão do Cloud Shell, é necessário autorizar o Cloud Shell usando esse principal.

Escolha o principal certo para a tarefa

Há diferentes tipos de principais para uso humano e cargas de trabalho automatizadas. O tipo de principal que você precisa usar afeta a forma como você se autentica.

  • Contas de usuário: são Contas do Google para humanos realizarem trabalhos interativos, como tarefas administrativas incidentais, configuração não programática de serviços do Google Cloud , testes, experimentos e observabilidade.

    Você se autentica como uma conta de usuário com credenciais de usuário, como uma senha e um código único.

  • Contas de serviço: são contas específicas do Google Cloud que as cargas de trabalho podem usar para acessar serviços ou recursos. Normalmente, você não se autentica diretamente como uma conta de serviço. Em vez disso, anexe uma conta de serviço a um recurso, como uma VM do Compute Engine, ou use a identidade temporária de conta de serviço.

  • Principais federados: são identidades que referenciam contas de usuário ou de serviço em um provedor de identidade externo. Há dois tipos de principais federados compatíveis com Google Cloud, que têm nomes semelhantes:

Usar a CLI gcloud como um humano

Para tarefas interativas, normalmente você faz a autenticação com uma das seguintes opções:

  • Uma conta de usuário

  • Uma identidade de usuário federada usando a Federação de identidade de colaboradores

Contas de usuário

A maneira como você se autentica com uma conta de usuário na CLI gcloud depende se um navegador da Web está instalado no seu dispositivo.

Meu dispositivo tem um navegador da Web

Para fazer a autenticação com uma conta de usuário em um dispositivo com um navegador da Web, siga estas etapas:

  1. Execute o comando a seguir para iniciar o processo:

    gcloud auth login

  2. Siga o fluxo baseado no navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.

O comando gcloud auth login armazena credenciais de acesso no seu 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.

Meu dispositivo não tem um navegador da Web

Se o dispositivo em que você precisa usar a CLI gcloud não tiver um navegador da Web, autentique-se com sua conta de usuário em outro dispositivo confiável. Esse processo muda de acordo com o software instalado no outro dispositivo de confiança.

Autenticar usando outro dispositivo de confiança

Selecione qual software está disponível no outro dispositivo de confiança.

A CLI gcloud e um navegador da Web

Use a flag --no-browser para concluir o processo de autenticação em outro dispositivo com um navegador da Web e a CLI gcloud instalada:

  1. Execute o seguinte comando no dispositivo original em que você quer usar a CLI gcloud:

    Linux e macOS 

    gcloud auth login \
    --no-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-browser

  2. Copie o comando gcloud que começa com gcloud auth login --remote-bootstrap=" para usar no outro dispositivo.

  3. Acesse outro dispositivo confiável que tenha um navegador da Web e a CLI gcloud versão 372.0.0 ou mais recente instalada.

  4. No terminal, execute o comando que você copiou antes, que começa com gcloud auth login --remote-bootstrap=", e conclua o fluxo baseado em navegador.

  5. No terminal, copie o URL que começa com https://localhost para usar no dispositivo original.

  6. Volte para o dispositivo original.

  7. No terminal, no prompt, cole o URL https://localhost que você copiou antes. Pressione Enter ou Return no teclado para concluir o processo.

O comando gcloud auth login armazena credenciais de acesso no seu 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.

Somente no navegador da Web

Use a flag --no-launch-browser para concluir o processo de autenticação usando o navegador da Web de outro dispositivo:

  1. Execute o seguinte comando no dispositivo original em que você quer usar a CLI gcloud:

    Linux e macOS 

    gcloud auth login \
    --no-launch-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-launch-browser

  2. Copie o URL que começa com https://accounts.google.com/o/oauth2/auth para usar no outro dispositivo.

  3. Acesse outro dispositivo confiável com um navegador da Web instalado.

  4. Abra um navegador da Web, acesse o URL que você copiou antes e conclua o fluxo baseado no navegador.

  5. Copie o código de verificação para usar no dispositivo original.

  6. Volte para o dispositivo original.

  7. No terminal, no prompt, cole o código de verificação que você copiou antes. Pressione Enter ou Return no teclado para concluir o processo.

O comando gcloud auth login armazena credenciais de acesso no seu 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.

Identidades de usuário federadas

É possível usar a CLI gcloud com uma identidade de usuário federada gerenciada em um provedor de identidade (IdP) externo. Isso é feito com a federação de identidade de colaboradores.

As instruções a seguir pressupõem que você já tenha um pool e um provedor da federação de identidade de colaboradores configurados para trabalhar com seu IdP.

Para usar a CLI gcloud com uma identidade de usuário federada, crie um arquivo de configuração de login e faça login usando um fluxo baseado em navegador:

  1. Execute o comando a seguir 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 como o IdP configurado no provedor do pool de identidade de colaboradores. O arquivo não contém informações confidenciais.

    O conteúdo do arquivo de configuração de login é semelhante a este:

    {
  "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"
}

  2. 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 inicia o processo de autenticação. Siga o fluxo baseado no navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.

    Para parar de usar o 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 inicia o processo de autenticação. Siga o fluxo baseado no navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.

    Para parar de usar o arquivo de configuração de login para comandos gcloud auth login, desative a 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 credenciais de acesso no seu 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 a CLI gcloud com cargas de trabalho

Para cargas de trabalho automatizadas, normalmente você faz a autenticação com uma das seguintes opções:

  • Uma identidade federada da carga de trabalho usando a federação de identidade da carga de trabalho

  • Uma conta de serviço usando a representação

Identidades federadas da carga de trabalho

É possível usar a CLI gcloud com uma identidade federada da carga de trabalho. Isso é feito com a federação de identidade da carga de trabalho.

Uma carga de trabalho pode acessar recursos do Google Cloud diretamente agindo como um principal definido por um pool de identidades da carga de trabalho ou usar a identidade temporária de uma conta de serviço anexada a um pool de identidades da carga de trabalho.

Recomendamos usar o método de acesso direto para evitar contas de serviço com permissões excessivas e registrar o acesso a recursos usando o identificador do principal federado. Use a identidade temporária de conta de serviço apenas quando as APIsGoogle Cloud não forem compatíveis com a federação de identidade da carga de trabalho.

As instruções a seguir presumem que você já tenha um pool e um provedor de federação de identidade da carga de trabalho configurados para trabalhar com seu IdP.

  1. Crie um arquivo de configuração de credenciais para a federação de identidade da carga de trabalho seguindo as instruções do provedor de identidade compatível.

  2. Defina o caminho para o arquivo de configuração de credenciais em uma variável de ambiente, como uma propriedade na configuração ativa da CLI gcloud ou com o comando gcloud auth login:

    Variável de ambiente

    Defina a variável de ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE como o caminho do arquivo de configuração de credenciais. A CLI gcloud referencia o arquivo sempre que executa um comando e recebe uma credencial do seu IdP. Essa credencial é trocada por um token de acesso para Google Cloud.

    Para parar de usar o arquivo de configuração de credenciais, limpe a variável de ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    Configuração da CLI gcloud

    Defina a propriedade auth/credential_file_override da configuração ativa da CLI gcloud como o caminho do arquivo de configuração de credenciais com o seguinte comando:

    gcloud config set auth/credential_file_override CONFIGURATION_PATH

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

    Para parar de usar o arquivo de configuração de credenciais por padrão para comandos gcloud, remova a propriedade com o seguinte comando:

    gcloud config unset auth/credential_file_override

    gcloud auth login

    Execute o comando a seguir usando a flag --cred-file:

    Linux e macOS 

    gcloud auth login \
    --cred-file=CONFIGURATION_PATH

    Windows (PowerShell) 

    gcloud auth login `
    --cred-file=CONFIGURATION_PATH

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

    O comando gcloud auth login armazena credenciais de acesso no seu 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.

Contas de serviço

É possível usar a CLI gcloud com uma conta de serviço das seguintes maneiras:

  • Em um recurso que expõe um servidor de metadados do Compute Engine, como uma instância de VM do Compute Engine ou um serviço do Cloud Run. A CLI gcloud usa qualquer conta de serviço anexada ao recurso para autenticação por padrão.

  • Usando outro principal para representar uma conta de serviço.

  • Usando uma chave de conta de serviço.

Identidade temporária de conta de serviço

Para acesso a recursos que normalmente não estão disponíveis para seu principal, recomendamos gerenciar o escalonamento de privilégios com o Privileged Access Manager em vez de usar a identidade temporária de conta de serviço.

Se o Privileged Access Manager não for adequado ao seu caso de uso, siga estas etapas para usar a CLI gcloud com uma conta de serviço:

  1. Para representar uma conta de serviço, verifique se a API Service Account Credentials está ativada no seu projeto.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

  2. Escolha um principal para usar na representação de uma conta de serviço.

  3. Para garantir que o principal tenha a permissão necessária a fim de representar uma conta de serviço, peça ao administrador para conceder o papel do IAM de criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator) ao principal na conta de serviço. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Esse papel predefinido contém a permissão iam.serviceAccounts.getAccessToken que é necessária para representar uma conta de serviço.

    O administrador também pode conceder essa permissão ao principal com papéis personalizados ou outros papéis predefinidos.

  4. Autentique a CLI gcloud com a principal escolhida anteriormente, seja uma conta de usuário, identidade de usuário federada, identidade de carga de trabalho federada ou outra conta de serviço.

  5. Escolha uma conta de serviço para representar. Encontre uma conta de serviço ou crie uma.

  6. Copie o endereço de e-mail da conta de serviço.

  7. Escolha se você quer representar a conta de serviço em todos os comandos ou apenas em um:

    Todos os comandos

    Para usar a identidade temporária de conta de serviço com a CLI gcloud em comandos futuros, defina uma variável de ambiente ou uma propriedade na configuração ativa da CLI gcloud:

    • Variável de ambiente: defina a variável de ambiente CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT como o endereço de e-mail da conta de serviço.

      Para parar de usar a conta de serviço, limpe a variável de ambiente CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

    • Configuração da CLI gcloud: defina a propriedade auth/impersonate_service_account da configuração ativa da CLI gcloud com o seguinte comando:

      gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL

      Substitua SERVICE_ACCOUNT_EMAIL pelo endereço de e-mail da conta de serviço.

      Para parar de usar a identidade temporária de conta de serviço por padrão para comandos gcloud, cancele a definição da propriedade com o seguinte comando:

      gcloud config unset auth/impersonate_service_account

    Comando único

    Para usar a identidade temporária de conta de serviço com a CLI gcloud em um único comando, adicione a flag --impersonate-service-account a um comando de serviço da CLI gcloud.

    Por exemplo, para listar instâncias de VM do Compute Engine usando a identidade temporária de conta de serviço, execute o seguinte comando:

    Linux e macOS 

    gcloud compute instances list \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Windows (PowerShell) 

    gcloud compute instances list `
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Substitua SERVICE_ACCOUNT_EMAIL pelo endereço de e-mail da conta de serviço.

Chave da conta de serviço

Recomendamos que você use a federação de identidade da carga de trabalho para a maioria das cargas de trabalho executadas fora do Google Cloud. Use chaves de conta de serviço somente se a carga de trabalho for executada em um ambiente externo isolado que não ofereça suporte à federação de identidade da carga de trabalho.

A federação de identidade da carga de trabalho oferece as seguintes vantagens:

  • O acesso aos recursos é concedido pelo Identity and Access Management (IAM), com cargas de trabalho tratadas como principais individuais. Isso significa que não é necessário conceder permissões excessivas a uma conta de serviço para vários casos de uso.

  • É possível auditar qual carga de trabalho está executando qual tarefa. As ações não ficam ocultas atrás de um endereço de e-mail de conta de serviço.

  • A federação de identidade da carga de trabalho usa tokens de acesso de curta duração para reduzir o risco de exfiltração. As chaves de conta de serviço não expiram, a menos que sejam revogadas manualmente.

Para usar uma conta de serviço com a CLI gcloud em comandos futuros, faça o seguinte:

  1. Crie uma chave de conta de serviço e armazene-a como um arquivo em um local seguro no seu ambiente.

  2. Defina o caminho para o arquivo de chave da conta de serviço em uma variável de ambiente, como uma propriedade na configuração ativa da CLI gcloud ou com o comando gcloud auth login:

    • Variável de ambiente: defina a variável de ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE como o caminho do arquivo de chave da conta de serviço.

      Para parar de usar a chave da conta de serviço, limpe a variável de ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    • Configuração da CLI gcloud: defina a propriedade auth/credential_file_override da configuração ativa da CLI gcloud como o caminho da chave da conta de serviço com o seguinte comando:

      gcloud config set auth/credential_file_override KEY_PATH

      Substitua KEY_PATH pelo caminho para o arquivo de chave da conta de serviço.

      Para parar de usar a chave da conta de serviço por padrão para comandos gcloud, remova a propriedade com o seguinte comando:

      gcloud config unset auth/credential_file_override

    • gcloud auth login: execute o comando a seguir usando a flag --cred-file:

      Linux e macOS 

      gcloud auth login \
    --cred-file=KEY_PATH

      Windows (PowerShell) 

      gcloud auth login `
    --cred-file=KEY_PATH

      Substitua KEY_PATH pelo caminho para o arquivo de chave da conta de serviço.

      O comando gcloud auth login armazena credenciais de acesso no seu 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 a CLI gcloud com um token de acesso

Se você já tiver feito a autenticação para a CLI gcloud em outro dispositivo, poderá receber um token de acesso para a principal ativa desse dispositivo com o seguinte comando:

gcloud auth print-access-token

Em seguida, use esse token de acesso em outro dispositivo para acessar recursos do Google Cloud. O uso de um token de acesso evita a necessidade de definir um principal ativo e substitui qualquer principal ativo definido na configuração ativa da CLI gcloud.

Os tokens de acesso para contas de usuário têm uma vida útil padrão de uma hora.

É possível usar um token de acesso com a CLI gcloud para comandos futuros ou apenas um único comando.

Todos os comandos

Para usar um token de acesso com a CLI gcloud em comandos futuros, defina uma variável de ambiente ou uma propriedade na configuração ativa da CLI gcloud:

  • Variável de ambiente: defina a variável de ambiente CLOUDSDK_AUTH_ACCESS_TOKEN como a string do token de acesso.

    Para parar de usar o token de acesso, limpe a variável de ambiente CLOUDSDK_AUTH_ACCESS_TOKEN.

  • Configuração da CLI gcloud: armazene o token de acesso em um arquivo e defina a propriedade auth/access_token_file da configuração ativa da CLI gcloud como o caminho do arquivo com o seguinte comando:

    gcloud config set auth/access_token_file ACCESS_TOKEN_PATH

    Substitua ACCESS_TOKEN_PATH pelo caminho para o arquivo de token de acesso.

    Para parar de usar um token de acesso por padrão nos comandos gcloud, cancele a definição da propriedade com o seguinte comando:

    gcloud config unset auth/access_token_file

Comando único

Para usar um token de acesso com a CLI gcloud em um único comando, adicione a flag --access-token-file a um comando de serviço da CLI gcloud:

  1. Armazene o token de acesso em um arquivo.

  2. Use a flag --access-token-file com qualquer comando do serviço gcloud.

    Por exemplo, para listar instâncias de VM do Compute Engine usando um token de acesso, execute o seguinte comando:

    Linux e macOS 

    gcloud compute instances list \
    --access-token-file ACCESS_TOKEN_PATH

    Windows (PowerShell) 

    gcloud compute instances list `
    --access-token-file ACCESS_TOKEN_PATH

    Substitua ACCESS_TOKEN_PATH pelo caminho para o arquivo de token de acesso.

Prioridade das credenciais

Como vários métodos de autenticação podem ser usados em um ambiente, a CLI gcloud avalia os métodos em uma ordem específica para determinar qual principal usar. A CLI gcloud começa com as credenciais fornecidas e avalia se a representação da conta de serviço foi solicitada.

A ordem de avaliação das credenciais fornecidas é a seguinte:

  1. A variável de ambiente CLOUDSDK_AUTH_ACCESS_TOKEN, definida como a string do token de acesso.

  2. Arquivos de token de acesso. Os métodos usados para definir os caminhos de arquivo do token de acesso são avaliados na seguinte ordem:

    1. A flag de linha de comando --access-token-file, usada com qualquer comando da CLI gcloud.

    2. A variável de ambiente CLOUDSDK_AUTH_ACCESS_TOKEN_FILE.

    3. A propriedade auth/access_token_file na configuração ativa da CLI gcloud.

  3. Arquivos de credenciais. Os métodos usados para definir os caminhos dos arquivos de credenciais são avaliados na seguinte ordem:

    1. A variável de ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    2. A propriedade auth/credential_file_override na configuração ativa da CLI gcloud.

  4. O principal ativo definido pelo comando gcloud auth login ou pela definição da propriedade core/account.

Prioridade da identidade temporária de conta de serviço

Se a representação de conta de serviço tiver sido solicitada, a CLI gcloud verificará qual conta de serviço será representada depois que as credenciais forem fornecidas para o principal que está fazendo a representação. Os métodos usados para definir contas de serviço para representação são avaliados na seguinte ordem:

  1. A flag de linha de comando --impersonate-service-account.

  2. A variável de ambiente CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

  3. A conta de serviço definida pela propriedade auth/impersonate_service_account na configuração ativa.

Adicionar o Google Drive ao seu escopo

O escopo da CLI gcloud pode ser expandido para incluir o acesso ao Google Drive, além de Google Cloud. Isso significa que você pode usar Google Cloud tokens de acesso com o Google Drive.

Para expandir o escopo e incluir o Google Drive, adicione a flag --enable-gdrive-access ao autorizar a CLI gcloud:

Linux e macOS 

gcloud auth login \
    --enable-gdrive-access

Windows (PowerShell) 

gcloud auth login `
    --enable-gdrive-access

Em seguida, faça chamadas para as APIs do Google Drive usando a CLI gcloud para fornecer um token de acesso. Por exemplo, para listar todos os arquivos no seu Google Drive, faça a seguinte solicitação:

Linux e macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

Por exemplo, use um ID de arquivo da resposta do comando anterior para extrair texto de um arquivo do Google Docs:

Linux e macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Um caso de uso comum para o acesso ao Google Drive é usar o BigQuery com dados armazenados nas Planilhas Google.

Para saber mais sobre a API Google Drive, consulte Visão geral da API Google Drive.

Adicionar a CLI gcloud como um auxiliar de credenciais ao Docker

Para extrair dos registros de contêiner do Artifact Registry, é possível adicionar a CLI gcloud como um auxiliar de credenciais à sua configuração do Docker.

Para fazer isso, execute o comando gcloud auth configure-docker:

gcloud auth configure-docker REGION-docker.pkg.dev

Gerenciar principais e credenciais

É possível usar o comando gcloud auth login para autenticar vários principais no mesmo ambiente e autorizar a CLI gcloud a acessar recursos em nome deles. No entanto, apenas um principal pode estar ativo por vez. As seções a seguir abordam o gerenciamento dos principais na configuração da CLI gcloud, incluindo listagem, alternância entre eles e revogação das credenciais.

Listar principais

Para listar os principais cujas credenciais de acesso estão armazenadas no sistema local (ou seja, que foram autenticados usando gcloud auth login), execute o comando gcloud auth list:

gcloud auth list

A CLI gcloud lista os principais e mostra qual deles está ativo:

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

Substituições para o principal ativo não estão incluídas nesta lista. Elas incluem as seguintes variáveis de ambiente:

  • CLOUDSDK_AUTH_ACCESS_TOKEN
  • CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
  • CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

Para verificar se essas variáveis de ambiente estão definidas, execute o seguinte comando para seu sistema operacional:

Linux e macOS 

echo "$ENVIRONMENT_VARIABLE"

Windows (PowerShell) 

echo $env:ENVIRONMENT_VARIABLE

Substitua ENVIRONMENT_VARIABLE pela variável de ambiente que você quer verificar.

As substituições para o principal ativo também incluem as seguintes propriedades de configuração:

  • auth/access_token_file
  • auth/credential_file_override
  • auth/impersonate_service_account

Para verificar se essas propriedades de configuração estão definidas, execute o seguinte comando:

gcloud config list

Alternar principais ativos

Para mudar para um principal ativo que tenha credenciais armazenadas (ou seja, que já tenha concluído o fluxo gcloud auth login), execute gcloud config set:

gcloud config set account PRINCIPAL_IDENTIFIER

Substitua PRINCIPAL_IDENTIFIER pelo identificador completo do principal.

Você também pode alternar as principais das seguintes maneiras:

Definir a duração das sessões

Os administradores podem controlar por quanto tempo diferentes usuários podem acessar a CLI gcloud sem precisar fazer a autenticação novamente. Por exemplo, é possível forçar usuários com privilégios elevados a se autenticar novamente com mais frequência do que os usuários regulares.

Para mais informações, consulte Definir a duração da sessão para serviços do Google Cloud .

Revogar credenciais de um principal

É possível revogar as credenciais de principais que se autenticaram com gcloud auth login para que a CLI gcloud não possa agir em nome deles. A revogação invalida as credenciais nos servidores de autorização do Google e remove o principal da configuração ativa da CLI gcloud.

Para revogar as credenciais, execute gcloud auth revoke:

gcloud auth revoke PRINCIPAL_IDENTIFIER

Substitua PRINCIPAL_IDENTIFIER pelo identificador completo do principal.

Para revogar o acesso da CLI gcloud em todos os dispositivos associados à sua Conta do Google, acesse Apps e serviços de terceiros nas configurações da sua Conta do Google e exclua todas as conexões com o SDK Google Cloud.

Gerenciar credenciais armazenadas

A CLI gcloud armazena os arquivos de credenciais que usa no diretório de configuração da CLI gcloud. Para encontrar o local dos arquivos de credenciais, execute gcloud info:

gcloud info

A CLI gcloud imprime informações sobre a instalação. Os arquivos de credenciais são armazenados no diretório de configuração do usuário definido na saída:

User Config Directory: [/home/USERNAME/.config/gcloud]

Para Linux e macOS, o diretório de configuração da CLI gcloud geralmente é /home/USERNAME/.config/gcloud. Para Windows, é %APPDATA%\gcloud.

A seguir