Configurar o Application Default Credentials

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

A forma como você fornece credenciais ao ADC depende de onde seu código está sendo executado:

Ambiente de desenvolvimento local

Credenciais do usuário

Quando o código está sendo executado em um ambiente de desenvolvimento local, como uma estação de trabalho de desenvolvimento, a melhor opção é usar credenciais associadas à sua Conta do Google, também chamadas de credenciais do usuário.

Para fornecer suas credenciais de usuário ao ADC, use a Google Cloud CLI:

  1. Instale e inicialize a CLI gcloud, caso ainda não tenha feito isso.

  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.

O uso da CLI gcloud para fornecer credenciais ao ADC tem as seguintes limitações:

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

  • Esse método armazena suas credenciais em um arquivo no sistema de arquivos. Qualquer usuário com acesso ao seu sistema de arquivos pode usar essas credenciais. Quando você não precisar mais dessas credenciais, revogue-as:

    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, peça ao administrador de segurança que conceda a você os papéis necessários.

Credenciais do ADC e da gcloud

Ao fazer login na CLI gcloud, você usa o comando gcloud auth login para fornecer suas credenciais de usuário, que a CLI gcloud usa para autenticação e autorização para gerenciar recursos e serviços do Google Cloud. Como alternativa, é possível usar a sinalização --impersonate-service-account ou a propriedade auth/impersonate_service_account para representar uma conta de serviço. Essas credenciais são suas credenciais da gcloud.

Ao usar a CLI gcloud para fornecer credenciais ao ADC, você usa o comando gcloud auth application-default login. Esse comando coloca as credenciais em um local conhecido para uso pelo ADC em um ambiente de desenvolvimento local. Essas são suas credenciais locais do ADC.

Suas credenciais locais do ADC não são usadas pela CLI gcloud, e suas credenciais da gcloud não são usadas pelo ADC. São dois conjuntos distintos de credenciais.

A tabela a seguir mostra os dois comandos e o que eles fazem:

Comando Descrição
gcloud auth login

Aceita credenciais de usuário usadas para autenticar e autorizar o acesso aos serviços do Google Cloud.

gcloud auth application-default login

Aceita credenciais de usuário fornecidas ao Application Default Credentials para uso em um ambiente de desenvolvimento local.

Normalmente, você usa a mesma conta para fazer login na CLI gcloud e fornecer credenciais de usuário ao ADC, mas é possível usar contas diferentes, se necessário.

Para saber como fazer login na CLI gcloud, consulte Como inicializar a CLI gcloud.

Chaves da conta de serviço

Se não for possível usar credenciais de usuário para desenvolvimento local, use uma chave de conta de serviço. As chaves da conta de serviço criam risco desnecessário e precisam ser evitadas sempre que possível.

Se a política da organização tiver uma restrição que impede a criação de uma chave de conta de serviço, esse método não estará disponível para você.

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 a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina 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.

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 criar uma conta de serviço, consulte Como criar e gerenciar contas de serviço. 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.

Se a política da organização restringir a criação de contas de serviço, não é possível usar esse método para fornecer credenciais ao ADC.

Ambiente conteinerizado do Google Cloud

A autenticação para ambientes em contêineres é processada de maneira diferente entre os ambientes de desenvolvimento e produção.

Desenvolvimento para ambientes conteinerizados

Se você planeja conteinerizar seu aplicativo com o Google Kubernetes Engine ou o Anthos, use o ADC para desenvolvimento local com a CLI gcloud ou use um contêiner local

Ao usar um contêiner local como ambiente de desenvolvimento, você precisa disponibilizar seu arquivo de credenciais pessoais no contêiner. O complemento minikube do GCP Auth é uma maneira de fazer isso.

Ambientes de produção conteinerizados

A configuração da autenticação para ambientes conteinerizados do Google Cloud depende do ambiente que você está usando.

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.

Se a política da organização tiver uma restrição que impede a criação de uma chave de conta de serviço, esse método não estará disponível para você.

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 a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

Resolver problemas de configuração do ADC

Alguns problemas comuns que você pode encontrar ao usar o ADC incluem as seguintes situações:

As credenciais do usuário não funcionam

Se a sua solicitação de API retornar uma mensagem de erro informando que as credenciais do usuário final não são compatíveis com essa API, que a API não está sendo ativada no projeto ou que nenhum projeto de cota está definido, leia as seguintes informações.

Há dois tipos de APIs do Google Cloud:

  • APIs baseadas em recursos, que usam o projeto associado aos recursos que estão sendo acessados para faturamento e cota,

  • APIs baseadas em cliente, que usam o projeto associado à conta que acessa os recursos para faturamento e cota.

Quando você usa as credenciais da Conta do Google com uma API baseada no cliente, o projeto padrão associado à conta não pode ser usado para fins de faturamento.

Para resolver esse problema, faça uma das seguintes ações:

  1. Atualize o ADC para usar um projeto diferente como o projeto de faturamento:

    gcloud auth application-default set-quota-project YOUR_PROJECT

  2. Se você estiver chamando a API REST ou RPC diretamente, use o cabeçalho HTTP x-goog-user-project para especificar um projeto de faturamento em cada solicitação. Para detalhes, consulte Definir o projeto de cota com uma solicitação REST.

Você precisa ter a permissão do IAM serviceusage.services.use para que um projeto possa designá-lo como seu projeto de faturamento. A permissão serviceusage.services.use está incluída no papel de IAM de consumidor do Service Usage. Se você não tiver a permissão serviceusage.services.use para nenhum projeto, entre em contato com o administrador de segurança ou um proprietário do projeto que possa conceder a você o papel Consumidor do Service Usage no projeto.

Credenciais incorretas

Se as credenciais não estiverem fornecendo o acesso esperado ou não tiverem sido encontradas, inspecione as credenciais disponíveis para o ADC, na ordem em que o ADC procura, para ver o que pode estar errado. Veja alguns pontos a serem verificados:

  • Se você estiver usando a CLI gcloud para acessar o Google Cloud, não está usando as credenciais fornecidas para o ADC. Em vez disso, você está usando as credenciais fornecidas à CLI gcloud usando o comando gcloud auth login. Para mais informações sobre esses dois conjuntos de credenciais, consulte Credenciais do ADC e da gcloud.

  • Verifique se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida somente se você estiver usando uma chave de conta de serviço ou outro arquivo JSON para o ADC. As credenciais indicadas pela variável de ambiente têm precedência sobre outras credenciais, inclusive para a Identidade da carga de trabalho.

  • Confirme se o principal que está fazendo a solicitação tem os papéis do IAM necessários. Se você estiver usando credenciais de usuário, os papéis precisarão ser concedidos ao endereço de e-mail associado à Conta do Google. Se você estiver usando uma conta de serviço, ela precisará ter os papéis necessários.

  • Se você fornecer uma chave de API com a solicitação de API, ela terá precedência sobre o ADC em qualquer local. Se você tiver definido a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS e estiver usando uma chave de API, a API poderá retornar um aviso informando que as credenciais fornecidas ao ADC estão sendo ignoradas. Para interromper o alerta, desative a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Tipo de credencial não reconhecido

Se a solicitação de API retornar um erro que inclua "Erro ao criar a credencial no JSON. Tipo de credencial não reconhecido". Verifique se você está usando uma credencial válida. Os arquivos de ID do cliente não são compatíveis com credenciais do ADC.

A seguir