Forneça credenciais para 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 fornecer credenciais padrão de aplicativos (ADC) para uso por bibliotecas de cliente do Cloud e bibliotecas de cliente da API do Google em uma variedade de ambientes.

O ADC é uma estratégia usada pelas Bibliotecas de cliente do Cloud e bibliotecas de cliente da API do Google para encontrar automaticamente credenciais com base no ambiente do aplicativo e usá-las para autenticação nas APIs do Google Cloud. Quando você configura o ADC e usa uma biblioteca de cliente, seu código pode ser executado em um ambiente de desenvolvimento ou produção sem mudar como o aplicativo faz a autenticação 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 precisará fornecer credenciais usando o ADC. Para saber se uma API aceita chaves de API, 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 não funcionam com alguns métodos e APIs, como a API Cloud Translation ou a API Cloud Vision. 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.

Tipos de credenciais da gcloud

Agcloud auth application-default login fornece uma maneira de armazenar as credenciais da sua Conta do Google no local conhecido para uso pelo ADC, mas essas credenciais são usadas apenas pelas bibliotecas de cliente e pelo ADC. Ao executar comandos na CLI gcloud, você está usando as credenciais fornecidas ao fazer login na CLI gcloud usando o comando gcloud auth login.

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 para o local da chave.

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.

Ambiente de desenvolvimento conteinerizado

Se você estiver fazendo o desenvolvimento local em um ambiente conteinerizado, disponibilize o arquivo de credenciais pessoais para o contêiner. O complemento minikube do GCP Auth é uma maneira de fazer isso.

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 tiver uma restrição que restringe a criação de contas de serviço, não será possível usar esse método para configurar credenciais para o ADC.

Ambiente conteinerizado do Google Cloud

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

Quando estiver pronto para migrar para o ambiente conteinerizado do Google Cloud, será necessário entender como o ambiente é compatível com contas de autenticação e serviço.

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 para o local da chave.

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, atualize o ADC para usar um projeto diferente como o projeto de faturamento:

gcloud auth application-default set-quota-project YOUR_PROJECT

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.

O projeto de faturamento não está incluído no token retornado do ADC para solicitações REST. Se você estiver usando o ADC com uma solicitação REST, consulte Como definir o projeto de cota com uma solicitação REST.

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:

  • 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