Configurar o Application Default Credentials

Nesta página, descrevemos como configurar o Application Default Credentials (ADC) para uso por bibliotecas de cliente do Cloud, bibliotecas de cliente da API do Google e por APIs REST e RPC em uma série de ambientes. Configure o ADC fornecendo credenciais para ele no ambiente em que o código está em execução.

O Application Default Credentials (ADC) é uma estratégia usada pelas bibliotecas de autenticação do Google para encontrar credenciais automaticamente com base no ambiente do aplicativo. As bibliotecas de autenticação disponibilizam essas credenciais para as bibliotecas de cliente do Cloud e as bibliotecas de cliente da API do Google. Ao usar o ADC, o código pode ser executado em um ambiente de desenvolvimento ou produção sem mudar a forma como o aplicativo é autenticado nos serviços e nas APIs do Google Cloud.

Para mais informações sobre onde o ADC procura credenciais e em que ordem, consulte Como o Application Default Credentials funciona.

Se você estiver usando chaves de API, não é necessário configurar o ADC. Para saber mais, consulte Como usar chaves de API.

Como fornecer credenciais ao ADC

Escolha o ambiente em que o código está sendo executado:

Ambiente de desenvolvimento local

É possível fornecer suas credenciais de usuário ou credenciais da conta de serviço para o ADC em um ambiente de desenvolvimento local.

Credenciais do usuário

Quando seu código está sendo executado em um ambiente de desenvolvimento local, como uma estação de trabalho de desenvolvimento, a melhor opção é usar as credenciais associadas à sua conta de usuário.

Ao fornecer credenciais de usuário para criar um arquivo ADC local, você precisa estar ciente dos seguintes fatos:

  • As credenciais do usuário podem não funcionar para alguns métodos e APIs, como a API Cloud Translation ou a API Cloud Vision, sem parâmetros ou configurações extras. Se você receber uma mensagem de erro sobre a API não estar ativada no projeto ou se não houver um projeto de cota disponível, consulte Solução de problemas de configuração do ADC.

  • O ADC local contém seus tokens de acesso e atualização. Qualquer usuário com acesso ao seu sistema de arquivos pode usar essas credenciais. Se você não precisar mais dessas credenciais locais, poderá revogá-las usando o comando gcloud auth application-default revoke.

  • Se a Conta do Google não tiver os papéis necessários do Identity and Access Management (IAM) no projeto, é possível que o código não consiga acessar alguns recursos. Se isso acontecer, alguém precisará conceder a você os papéis necessários.

  • Seu arquivo ADC local está associado à sua conta de usuário, não à sua configuração da CLI do gcloud. Alterar para uma configuração diferente da CLI da gcloud não afeta seu arquivo ADC local ou as credenciais fornecidas ao ADC.

A forma como você fornece as credenciais de usuário para o ADC depende de a conta de usuário ser gerenciada pelo Google (ou seja, ser uma Conta do Google) ou por outro provedor de identidade (IdP). e federadas com a federação de identidade de colaboradores.

Forneça as credenciais de usuário para sua Conta do Google

Para fornecer suas credenciais de usuário no ADC para uma Conta do Google, use a CLI do Google Cloud:

  1. Instale e inicialize a CLI gcloud.

    Ao inicializar a gcloud CLI, especifique um projeto do Google Cloud em que você tem permissão para acessar os recursos necessários para o aplicativo.

  2. Crie o arquivo de credenciais:

    gcloud auth application-default login

    Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.

Fornecer credenciais do usuário para uma conta gerenciada por um IdP externo

Para fornecer as credenciais de usuário de uma conta de usuário gerenciada por um IdP externo e federada com a federação de identidade de colaboradores, você precisa do nome do provedor do pool de funcionários. Seu administrador poderá fornecer essas informações. O nome do provedor do pool de força de trabalho tem o seguinte formato:

locations/global/workforcePools/POOL_ID/provider/PROVIDER_ID

Forneça suas credenciais de usuário no ADC para uma conta de usuário federada:

  1. Crie o arquivo de configuração de login e defina a propriedade auth/login_config_file da CLI gcloud apontando para o local com o comando iam Spanner-pools create-login-config:

    gcloud iam workforce-pools create-login-config PROVIDER_ID \
--output-file=LOGIN_CONFIG_FILE --activate

    Substitua:

    • PROVIDER_ID: o ID do provedor
    • LOGIN_CONFIG_FILE: um caminho para o arquivo de configuração especificado. Por exemplo, login.json.

    O arquivo criado é semelhante ao exemplo a seguir:

    {
"type": "external_account_authorized_user_login_config",
"audience": "//iam.googleapis.com/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. Faça login na CLI gcloud usando o arquivo de login:

    gcloud auth login

  3. Inicialize a CLI gcloud.

    gcloud init

  4. Crie o arquivo ADC local:

    gcloud auth application-default login

Saiba mais em Federação de identidade de colaboradores.

Credenciais da conta de serviço

É possível configurar o ADC com credenciais de uma conta de serviço usando a representação da conta de serviço ou uma chave de conta de serviço.

Identidade temporária de conta de serviço

É possível usar a representação de conta de serviço para configurar um arquivo local Application Default Credentials (ADC). As bibliotecas de cliente compatíveis com a representação podem usar essas credenciais automaticamente. Os arquivos ADC locais criados com a representação são compatíveis com os seguintes idiomas:

  • C#
  • Go
  • Java
  • Node.js
  • Python

Você precisa ter o papel do IAM "Criador de token da conta de serviço" (roles/iam.serviceAccountTokenCreator) na conta de serviço que está representando. Para mais informações, consulte Papéis necessários.

Use a representação de conta de serviço para criar um arquivo ADC local: 

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Chaves da conta de serviço

Se não for possível usar as credenciais de usuário ou a representação de conta de serviço para desenvolvimento local, use uma chave de conta de serviço.

Para criar uma chave de conta de serviço e disponibilizá-la para o ADC, faça o seguinte:

  1. Crie uma conta de serviço com os papéis de que seu aplicativo precisa e uma chave para essa conta de serviço. Para fazer isso, siga as instruções em Como criar uma chave de conta de serviço.

  2. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém suas credenciais. Essa variável só se aplica à sessão de shell atual. Assim, se você abrir uma nova sessão, precisará definir a variável novamente.

Ambiente de desenvolvimento baseado na nuvem do Google Cloud

Quando você usa um ambiente de desenvolvimento baseado na nuvem do Google Cloud, como o Cloud Shell ou o Cloud Code, a ferramenta usa as credenciais fornecidas quando você fez login e gerencia todas as autorizações necessárias. Não é possível usar a CLI da gcloud para fornecer credenciais ao ADC nesses ambientes. Se você precisar fornecer uma conta de usuário diferente para o ADC, ou fornecer credenciais usando uma conta de serviço, use um ambiente de desenvolvimento local ou um recurso de computação do Google Cloud como seu ambiente de desenvolvimento.

Serviços do Google Cloud compatíveis com a anexação de uma conta de serviço

Alguns serviços do Google Cloud, como Compute Engine, App Engine e Cloud Functions, permitem a anexação de uma conta de serviço gerenciada pelo usuário a alguns tipos de recursos. Geralmente, a vinculação de uma conta de serviço acontece quando os recursos desse serviço podem ser executados ou incluem o código do aplicativo. Quando você anexa uma conta de serviço a um recurso, o código em execução no recurso pode usar essa conta de serviço como sua identidade.

Anexar uma conta de serviço gerenciada pelo usuário é a maneira preferida de fornecer credenciais ao ADC para código de produção em execução no Google Cloud.

Se precisar de ajuda para determinar os papéis que você precisa fornecer à conta de serviço, consulte Escolher papéis predefinidos.

Para informações sobre quais recursos podem ser anexados a uma conta de serviço e ajuda para anexar a conta de serviço ao recurso, consulte a documentação do IAM sobre como anexar uma conta de serviço.

Configure a autenticação:

  1. Crie a conta de serviço: 

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço.

  2. Para conceder acesso ao projeto e aos recursos, conceda um papel à conta de serviço: 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

    Substitua:

    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
    • PROJECT_ID: o ID do projeto em que você criou a conta de serviço
    • ROLE: o papel a ser concedido
  3. Para conceder outro papel à conta de serviço, execute o comando que você fez na etapa anterior.

  4. Conceda à sua Conta do Google um papel que permita que você use os papéis da conta de serviço e anexe a conta de serviço a outros recursos: 

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

    Substitua:

    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
    • PROJECT_ID: o ID do projeto em que você criou a conta de serviço
    • USER_EMAIL: o endereço de e-mail da sua Conta do Google

GKE ou GKE Enterprise

A autenticação de aplicativos em contêineres em execução no GKE ou no GKE Enterprise é processada de maneira diferente entre os ambientes de teste locais e os ambientes do Google Cloud.

Testar aplicativos em contêiner localmente

Para testar o aplicativo em contêiner na estação de trabalho local, configure contêineres para autenticar com seu arquivo de credenciais local. Para testar os contêineres, use uma implementação local do Kubernetes, como minikube e o complemento gcp-auth.

Execute aplicativos em contêiner no Google Cloud

Você configura a autenticação para ambientes em contêiner do Google Cloud de maneira diferente, dependendo do contexto:

No local ou outro provedor de nuvem

Se o aplicativo estiver sendo executado fora do Google Cloud, será necessário fornecer credenciais reconhecidas pelo Google Cloud para usar os serviços do Google Cloud.

Federação de identidade da carga de trabalho

A maneira mais comum de autenticar com o Google Cloud usando credenciais de um provedor de identidade diferente é usarfederação de identidade da carga de trabalho ; você cria um arquivo de configuração de credenciais e define o GOOGLE_APPLICATION_CREDENTIALS para apontar para ela. Essa abordagem é mais segura do que criar uma chave de conta de serviço.

Para ajuda com a configuração da federação da identidade da carga de trabalho para o ADC, consulte Como configurar a federação de identidade da carga de trabalho e Como receber credenciais de curta duração com federação de identidade.

Chave da conta de serviço

Se não for possível configurar a federação de identidade da carga de trabalho, crie uma conta de serviço, conceda a ela os papéis do IAM necessários ao aplicativo e crie uma chave para a conta de serviço.

Para criar uma chave de conta de serviço e disponibilizá-la para o ADC, faça o seguinte:

  1. Crie uma conta de serviço com os papéis de que seu aplicativo precisa e uma chave para essa conta de serviço. Para fazer isso, siga as instruções em Como criar uma chave de conta de serviço.

    Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém suas credenciais. Essa variável só se aplica à sessão de shell atual. Assim, se você abrir uma nova sessão, precisará definir a variável novamente.

A seguir