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.
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
- Ambientes de desenvolvimento baseados na nuvem do Google Cloud
- Compute Engine ou outros serviços do Google Cloud compatíveis com a anexação de uma conta de serviço
- Google Kubernetes Engine ou GKE Enterprise
- No local ou outro provedor de nuvem
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 configurar o ADC com sua conta de usuário, é importante estar ciente dos seguintes fatos:
A configuração do ADC com uma conta de usuário pode não funcionar para alguns métodos e APIs, como a API Cloud Translation ou Cloud Vision, sem parâmetros ou configurações extras. Se aparecer uma mensagem de erro informando que a API não está ativada no projeto ou que não há projeto de cota disponível, consulte As credenciais do usuário não estão funcionando.
O arquivo ADC local contém o token de atualização. Qualquer usuário com acesso ao seu sistema de arquivos pode usá-lo para receber um token de acesso válido. Se você não precisar mais dessas credenciais locais, poderá revogá-las usando o comando
gcloud auth application-default revoke
.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 gcloud pode alterar a identidade usada pela CLI gcloud, mas isso não afeta o arquivo ADC local ou a configuração do ADC.
A configuração do ADC com sua conta de usuário depende de a conta de usuário ser gerenciada pelo Google (em outras palavras, é uma Conta do Google) ou por outro provedor de identidade (IdP). e federadas usando a federação de identidade de colaboradores.
Configurar o ADC com sua Conta do Google
Para configurar o ADC com uma Conta do Google, use a CLI do Google Cloud:
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
-
Create local authentication credentials for your user account:
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.
Configurar o ADC com uma conta gerenciada por um IdP externo
Para configurar o ADC para uma conta de usuário gerenciada por um IdP externo e federada com a federação de identidade de colaboradores:
-
After Installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command:
gcloud init
-
Create local authentication credentials for your user account:
gcloud auth application-default login
If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.
Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.
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
Agora é possível usar bibliotecas de cliente com as linguagens compatíveis da mesma forma que você faria depois de configurar um arquivo local do ADC com credenciais de usuário. As credenciais são encontradas automaticamente pelas bibliotecas de autenticação. Para mais informações, consulte Autenticar para usar bibliotecas de cliente.
Chaves da conta de serviço
Se não for possível usar uma conta de usuário ou a representação de uma 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:
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.
Ambientes de desenvolvimento baseados 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 gcloud para configurar o ADC nesses ambientes. Se você precisar usar uma conta de usuário diferente para configurar o ADC ou uma conta de serviço, use um ambiente de desenvolvimento local ou um recurso de computação do Google Cloud como 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.
Set up authentication:
-
Create the service account:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
Replace
SERVICE_ACCOUNT_NAME
with a name for the service account. -
To provide access to your project and your resources, grant a role to the service account:
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
Replace the following:
SERVICE_ACCOUNT_NAME
: the name of the service accountPROJECT_ID
: the project ID where you created the service accountROLE
: the role to grant
- To grant another role to the service account, run the command as you did in the previous step.
-
Grant the required role to the principal that will attach the service account to other resources.
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
Replace the following:
SERVICE_ACCOUNT_NAME
: the name of the service accountPROJECT_ID
: the project ID where you created the service accountUSER_EMAIL
: the email address for a Google Account
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 ambiente:
- Para o GKE Enterprise, consulte a visão geral da autenticação e Usar a federação de identidade da carga de trabalho da frota para o GKE.
- Para o GKE, consulte Acessar APIs do Google Cloud das cargas de trabalho do GKE.
- Para exibição do Knative, consulte Como usar a federação de identidade da carga de trabalho do GKE para exibição do Knative.
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 externo (idp) é 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 receber ajuda com a configuração da federação de identidade da carga de trabalho para o ADC, consulte Federação de identidade da carga de trabalho com outras nuvens.
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:
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
- Saiba mais sobre como o ADC encontra credenciais.
- Autenticar para usar bibliotecas de cliente do Cloud.
- Conheça os métodos de autenticação.