Autorizar o gcloud CLI

Para acessar Google Cloud, normalmente você precisará autorizar a CLI do Google Cloud. Esta página demonstra as opções de autorização disponíveis e mostra como gerenciar as contas que você usa para autorização. Se estiver usando uma instância do Compute Engine ou o Cloud Shell, não será necessário autorizar a CLI do gcloud.

Tipos de contas

Para conceder autorização ao gcloud CLI para acessarGoogle Cloud, você pode usar uma conta de usuário ou uma conta de serviço .

Uma conta de usuário é uma Google Cloud Conta que permite que usuários finais se autentiquem no seu aplicativo. Para a maioria dos casos de uso comuns, especialmente interativamente usando a CLI do gcloud, usar uma conta de usuário é a prática recomendada.

Uma conta de serviço é uma Google Cloud conta associada à suaGoogle Cloud projeto e não um usuário específico. Você pode usar a conta de serviço integrada disponível ao usar as funções do Cloud Run, App Engine, Compute Engine ou Google Kubernetes Engine. Uma conta de serviço é recomendada para executar scripts da CLI do gcloud em várias máquinas.

Escolha um tipo de autorização

Você deve autorizar o Google Cloud CLI a gerenciar Google Cloudrecursos. Tanto o Google Cloud CLI quanto Google Cloud use OAuth2 para autenticação e autorização.

Escolha um dos seguintes tipos de autorização:

Para obter mais informações sobre autenticação e Google Cloud, consulte Visão geral da autenticação .

Autorizar com uma conta de usuário

Esta seção descreve como autorizar com uma conta de usuário.

Autenticação com uma conta do Google

Use os seguintes comandos da CLI do gcloud para autorizar o acesso com uma conta de usuário:

Durante a autorização, esses comandos obtêm credenciais de conta deGoogle Cloud e armazená-los no sistema local. A conta especificada se torna a conta ativa em sua configuração . A CLI do gcloud usa as credenciais armazenadas para acessarGoogle Cloud. Você pode ter qualquer número de contas com credenciais armazenadas para uma única instalação do gcloud CLI, mas apenas uma conta fica ativa por vez.

Execute o gcloud init

gcloud init autoriza o acesso e executa outras etapas comuns de configuração . gcloud init usa um fluxo de autorização baseado na web para autenticar a conta do usuário e conceder permissões de acesso.

Para autorizar o acesso e executar outras etapas comuns de configuração:

1. Execute gcloud init :

   gcloud init
   

   Ou, para impedir que o comando abra automaticamente um navegador da web:

   gcloud init --console-only
   

   Usar a flag --console-only é útil se você estiver executando o comando em um sistema remoto via ssh e não tiver acesso a um navegador nesse sistema. Você deve então abrir manualmente a URL fornecida em um navegador no seu sistema local para concluir o processo de autorização.

2. Siga o fluxo de autorização baseado no navegador para autenticar a conta e conceder permissões de acesso.

Para obter mais informações sobre gcloud init , consulte Inicializando o gcloud CLI .

Execute gcloud auth login

Executar gcloud auth login autoriza apenas a conta do usuário. Para autorizar o acesso sem realizar outras etapas de configuração, use uma das seguintes opções.

• Se você quiser autorizar o gcloud CLI em uma máquina com um navegador, siga estas etapas.

  1. Autorize o gcloud CLI:

     gcloud auth login
     

  2. Siga o fluxo de autorização baseado no navegador para autenticar a conta e conceder permissões de acesso.

• Se você quiser autorizar o gcloud CLI em uma máquina que não tem um navegador e puder instalar o gcloud CLI em outra máquina com um navegador, use o sinalizador --no-browser .

  1. Autorize o gcloud CLI:

     gcloud auth login --no-browser
     

  2. Copie o comando longo que começa com gcloud auth login --remote-bootstrap=" .

  3. Cole e execute este comando na linha de comando de uma máquina diferente e confiável que tenha instalações locais de um navegador da web e da ferramenta CLI gcloud versão 372.0 ou posterior.

  4. Copie a saída de URL longa da máquina com o navegador da web.

  5. Cole a URL longa de volta na primeira máquina sob o prompt "Digite a saída do comando acima" e pressione Enter para concluir a autorização.

• Se você quiser autorizar a CLI do gcloud em uma máquina sem navegador e não puder instalar a CLI do gcloud em outra máquina com navegador, use a sinalização --no-launch-browser . A sinalização --no-launch-browser impede que o comando abra um navegador da web automaticamente.

  1. Autorize o gcloud CLI:

     gcloud auth login --no-launch-browser
     

  2. Copie o URL longo que começa com https://accounts.google.com/o/oauth2/auth...

  3. Cole esta URL no navegador de uma máquina diferente e confiável que tenha um navegador da web.

  4. Copie o código de autorização da máquina com o navegador da web.

  5. Cole o código de autorização novamente na primeira máquina no prompt "Digite o código de verificação" e pressione Enter para concluir a autorização.

• Se você já tiver um token de acesso, use um dos seguintes métodos para passá-lo para a CLI do gcloud:

  • Armazene o token de acesso em um arquivo e defina seu caminho por meio do sinalizador --access-token-file .
  • Armazene o token de acesso em um arquivo e defina seu caminho na propriedade auth/access_token_file .
  • Defina a variável de ambiente CLOUDSDK_AUTH_ACCESS_TOKEN como o valor do token de acesso.

Autenticação com a Federação de Identidade da Força de Trabalho

Esta seção descreve como fazer login no gcloud CLI usando o Workforce Identity Federation.

login baseado em navegador da CLI do gcloud

Para fazer login na CLI do gcloud usando um fluxo de login baseado em navegador, faça o seguinte:

1. Crie um arquivo de configuração de login.

   Para criar o arquivo de configuração de login, execute o seguinte comando. Opcionalmente, você pode ativar o arquivo como padrão para a CLI do gcloud adicionando o sinalizador --activate . Você pode então executar gcloud auth login sem especificar o caminho do arquivo de configuração a cada vez.

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

   Substitua o seguinte:

   • WORKFORCE_POOL_ID : o ID do pool de força de trabalho
   • PROVIDER_ID : o ID do provedor
   • LOGIN_CONFIG_FILE_PATH : o caminho para um arquivo de configuração que você especificar — por exemplo, login.json

   O arquivo contém os endpoints usados ​​pela CLI do gcloud para habilitar o fluxo de autenticação baseado em navegador e definir o público como o IdP configurado no provedor do pool de identidades da força de trabalho. O arquivo não contém informações confidenciais.

   A saída é semelhante à seguinte:

   {
     "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://googleapis.com/v1/introspect",
   }

   Para impedir que gcloud auth login use esse arquivo de configuração automaticamente, você pode desconfigurá-lo executando gcloud config unset auth/login_config_file .

2. Faça login usando a autenticação baseada em navegador.

   Para autenticar usando a autenticação de login baseada em navegador, você pode usar um dos seguintes métodos:

   • Se você usou o sinalizador --activate ao criar o arquivo de configuração ou se ativou o arquivo de configuração com gcloud config set auth/login_config_file , o gcloud CLI usará seu arquivo de configuração 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_PATH

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

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

• Se você usou o sinalizador --activate ao criar o arquivo de configuração ou se ativou o arquivo de configuração com gcloud config set auth/login_config_file , deverá executar o seguinte comando para desativá-lo:

  gcloud config unset auth/login_config_file

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

Login sem interface da CLI do gcloud

Para fazer login no gcloud CLI usando um fluxo headless, faça o seguinte:

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

gcloud auth login --cred-file="config.json"

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

gcloud auth list

Autorizar com uma conta de serviço

O comando gcloud auth login pode autorizar o acesso com uma conta de serviço usando um arquivo de credencial armazenado no seu sistema de arquivos local. Essa credencial pode ser uma credencial de usuário com permissão para representar a conta de serviço, um arquivo de configuração de credencial para a Federação de Identidade da Carga de Trabalho ou uma chave de conta de serviço.

Autorizar uma conta de serviço usando a representação de conta de serviço

Para autorizar o gcloud CLI a usar credenciais de conta de serviço personificadas , faça o seguinte:

1. No Google Cloud console, vá para a página Contas de serviço.

   Ir para Contas de Serviço

2. Escolha uma conta existente ou crie uma nova conta clicando em Criar conta de serviço .

3. Para obter a permissão necessária para representar uma conta de serviço, peça ao administrador que lhe conceda a função do IAM " Criador de Token de Conta de Serviço" ( roles/iam.serviceAccountTokenCreator ) na conta de serviço. Para obter mais informações sobre como conceder funções, consulte Gerenciar acesso a projetos, pastas e organizações .

   Esta função predefinida contém a permissão iam.serviceAccounts.getAccessToken , que é necessária para representar uma conta de serviço.

   Você também pode obter essa permissão com funções personalizadas ou outras funções predefinidas .

4. Autorize o gcloud CLI com sua identidade de usuário executando gcloud auth login .

5. Para configurar o gcloud CLI para usar a identidade e o acesso fornecidos por uma conta de serviço por padrão, use o comando gcloud CLI config :

   gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL
   

6. Para parar de usar credenciais de conta de serviço personificadas com o gcloud CLI por padrão, desative o sinalizador com o comando gcloud CLI config :

   gcloud config unset auth/impersonate_service_account
   

Autorizar uma conta de serviço usando a Federação de Identidade de Carga de Trabalho

Para autorizar o gcloud CLI com uma conta de serviço usando credenciais externas da Workload Identity Federation, faça o seguinte:

1. No Google Cloud console, vá para a página Contas de serviço.

   Ir para Contas de Serviço

2. Escolha uma conta existente ou crie uma nova conta clicando em Criar conta de serviço .

3. Crie um arquivo de configuração de credencial para a Federação de Identidade de Carga de Trabalho seguindo as instruções do seu provedor de identidade compatível.

4. Para ativar sua conta de serviço, execute gcloud auth login com o sinalizador --cred-file :

   gcloud auth login --cred-file=CONFIGURATION_FILE
   

   Substitua CONFIGURATION_FILE pelo caminho para um arquivo de configuração de credencial para Federação de Identidade de Carga de Trabalho.

Autorizar uma conta de serviço usando uma chave de conta de serviço

Para autorizar o gcloud CLI com uma conta de serviço usando uma chave de conta de serviço, faça o seguinte:

1. No Google Cloud console, vá para a página Contas de serviço.

   Ir para Contas de Serviço

2. Escolha uma conta existente ou crie uma nova conta clicando em Criar conta de serviço .

3. Para criar chaves de conta de serviço, consulte as instruções do IAM para Criar uma chave de conta de serviço .

4. Para ativar sua conta de serviço, execute gcloud auth login com o sinalizador --cred-file :

   gcloud auth login --cred-file=KEY_FILE
   

   Substitua KEY_FILE pelo caminho para um arquivo de chave de conta de serviço.

Listar contas

Para listar as contas cujas credenciais estão armazenadas no sistema local, execute gcloud auth list :

gcloud auth list

O gcloud CLI lista as contas e mostra qual conta está ativa:

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

Trocar a conta ativa

Para alternar a conta ativa, execute gcloud config set :

gcloud config set account ACCOUNT

onde [ACCOUNT] é o endereço de e-mail completo da conta.

Você também pode alternar contas criando uma configuração separada que especifique cada conta e alternando entre configurações:

gcloud config configurations activate CONFIGURATION

Se você quiser alternar a conta usada pelo gcloud CLI a cada invocação, substitua a conta ativa usando o sinalizador --account .

Definir duração da sessão autorizada

Como administrador, você pode controlar por quanto tempo diferentes usuários podem acessar a CLI do gcloud sem precisar se autenticar novamente. Por exemplo, você pode forçar usuários com privilégios elevados a se autenticarem novamente com mais frequência do que usuários comuns.

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

Revogar credenciais de uma conta

Você pode revogar credenciais quando quiser proibir o acesso de uma conta específica à CLI do gcloud. Não é necessário revogar credenciais para alternar entre contas.

Para revogar credenciais, execute gcloud auth revoke :

gcloud auth revoke ACCOUNT

Para revogar todo o acesso ao gcloud CLI para todas as máquinas, remova o gcloud CLI da lista de aplicativos que têm acesso à sua conta .

Trabalhar com arquivos de credenciais

Encontre seus arquivos de credenciais

Para encontrar a localização dos seus arquivos de credenciais, execute gcloud info :

gcloud info

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

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

Configurar credenciais padrão do aplicativo

A CLI do gcloud oferece suporte para o gerenciamento de Credenciais Padrão do Aplicativo (ADC) com o grupo de comandos gcloud auth application-default . Para disponibilizar as credenciais do usuário para o ADC, execute gcloud auth application-default login :

gcloud auth application-default login

Essas credenciais não são usadas pela CLI do gcloud . Para saber mais sobre como configurar o ADC, consulte Configurar credenciais padrão do aplicativo .

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

O que vem a seguir

• Para saber mais sobre autenticação e Google Cloud, consulte Visão geral da autenticação .
• Para saber mais sobre como personalizar o gcloud CLI, consulte Propriedades do gcloud CLI .
• Para saber mais sobre como gerenciar conjuntos nomeados de propriedades do gcloud CLI, consulte Configurações do gcloud CLI .