Autenticar para a CLI gcloud

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

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ê em 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 da CLI gcloud para agir em seu nome estão incluídas no processo de inicialização. Talvez seja necessário se 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 pode acessar os mesmos recursos que essa conta 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:

  • Federação de identidade de colaboradores: permite que usuários humanos façam login no Google Cloud com identidades gerenciadas por um provedor de identidade externo. Se a organização já tiver o logon único (SSO) configurado, você poderá usar esse tipo de identidade para autenticar o Google Cloud.

    Seu provedor de identidade precisa ser compatível com OpenID Connect (OIDC) ou SAML 2.0 para usar a federação de identidade de colaboradores.

  • Federação de identidade da carga de trabalho: permite que cargas de trabalho executadas fora do Google Cloud operem em recursos do Google Cloud .

    É possível usar a federação de identidade da carga de trabalho com cargas de trabalho que fazem autenticação usando certificados de cliente X.509; que são executadas no Amazon Web Services (AWS) ou Azure; no local Active Directory; serviços de implantação, como GitHub e GitLab; e com qualquer provedor de identidade compatível com OpenID Connect (OIDC) ou Security Assertion Markup Language (SAML) V2.0.

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.

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 da força de trabalho.

As instruções a seguir pressupõem que você já tenha um pool e um provedor da federação de identidade da força de trabalho 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 da força de trabalho.
   • 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 de 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.