Este tópico explica como autenticar um aplicativo como uma conta de serviço. Para informações gerais sobre autenticação nas APIs do Google Cloud, inclusive cenários e estratégias de autenticação comuns, consulte Visão geral da autenticação. Para mais informações sobre contas de serviço, consulte Contas de serviço na documentação do gerenciamento de identidade e acesso.
Como encontrar credenciais automaticamente
Se o aplicativo for executado em um ambiente do Google Cloud e você tiver anexado uma conta de serviço a ele, o aplicativo poderá recuperar as credenciais da conta de serviço. O aplicativo pode então usar as credenciais para chamar as APIs do Google Cloud.
É possível anexar contas de serviço a recursos de diversos serviços diferentes do Google Cloud, incluindo Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run e Cloud Functions. Recomendamos usar essa estratégia, porque ela é mais conveniente e segura do que transmitir as credenciais manualmente.
Além disso, recomendamos que você use as bibliotecas de cliente do Google Cloud para seu aplicativo. As bibliotecas de cliente do Google Cloud usam uma biblioteca chamada Application Default Credentials (ADC) para encontrar as credenciais da sua conta de serviço automaticamente. O ADC procura credenciais de conta de serviço na seguinte ordem:
Se a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
estiver definida, o ADC usará a chave da conta de serviço ou o arquivo de configuração apontado pela variável.Se a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
não estiver definida, o ADC usará a conta de serviço anexada ao recurso que está executando seu código.Essa conta de serviço pode ser uma conta de serviço padrão fornecida pelo Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run ou Cloud Functions. Também pode ser uma conta de serviço gerenciada pelo usuário criada por você.
Caso o ADC não use nenhuma das credenciais acima, um erro é gerado.
O exemplo de código a seguir ilustra como usar a biblioteca ADC no código do aplicativo. Para executar este exemplo, é preciso instalar a biblioteca de cliente do Cloud Storage.
C#
Go
Java
Node.js
PHP
Python
Ruby
Como transmitir credenciais manualmente
Se o aplicativo for executado em um ambiente sem nenhuma conta de serviço anexada, como no local ou em outro provedor de nuvem, use a federação de identidade da carga de trabalho.
Se não for possível usar a federação de identidade da carga de trabalho, crie uma conta de serviço e uma ou mais chaves de conta de serviço, que são credenciais associadas à conta de serviço. As chaves de conta de serviço podem ser transmitidas manualmente para seu aplicativo.
Consulte as práticas recomendadas para gerenciar chaves de conta de serviço.
Como criar uma conta de serviço
As etapas a seguir descrevem como criar uma conta de serviço se você não tiver uma:
Console
Crie uma conta de serviço:
-
No Console do Cloud, acesse a página Criar conta de serviço.
Acesse "Criar conta de serviço" - Selecione o projeto.
-
No campo Nome da conta de serviço, insira um nome. O Console do Cloud preenche o campo ID da conta de serviço com base nesse nome.
No campo Descrição da conta de serviço, insira uma descrição. Por exemplo,
Service account for quickstart
. - Clique em Criar e continuar.
-
Para fornecer acesso ao projeto, conceda os seguintes papéis à conta de serviço: Projeto > Proprietário.
Na lista Selecionar um papel, escolha um.
Para papéis adicionais, clique em
Adicionar outro papel e adicione cada papel adicional. - Clique em Continuar.
-
Clique em Concluído para terminar a criação da conta de serviço.
Não feche a janela do navegador. Você vai usá-la na próxima etapa.
Crie uma chave de conta de serviço:
- No Console do Cloud, clique no endereço de e-mail da conta de serviço que você criou.
- Clique em Chaves.
- Clique em Adicionar chave e em Criar nova chave.
- Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
- Clique em Fechar.
gcloud
Configure a autenticação:
-
Crie a conta de serviço:
gcloud iam service-accounts create NAME
Substitua
NAME
por um nome para a conta de serviço. -
Conceda papéis à conta de serviço. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM:
roles/owner
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çoROLE
: o papel a ser concedido
-
Gere o arquivo de chave:
gcloud iam service-accounts keys create FILE_NAME.json --iam-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Substitua:
FILE_NAME
: um nome para o arquivo de chaveSERVICE_ACCOUNT_NAME
: o nome da conta de serviço.PROJECT_ID
: o ID do projeto em que você criou a conta de serviço
Como transmitir credenciais por meio da variável de ambiente
Forneça credenciais de autenticação ao código do aplicativo
definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
. Essa
variável se aplica somente à sessão de shell atual. Se você quiser que a variável
seja aplicada em sessões de shell futuras, defina a variável no arquivo de inicialização de shell,
por exemplo, no arquivo ~/.bashrc
ou ~/.profile
.
Linux ou macOS
export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH
"
Substitua KEY_PATH
pelo caminho do arquivo JSON que
contém a chave da conta de serviço.
Exemplo:
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
Para PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH
"
Substitua KEY_PATH
pelo caminho do arquivo JSON que
contém a chave da conta de serviço.
Exemplo:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
Para prompt de comando:
set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH
Substitua KEY_PATH
pelo caminho do arquivo JSON que
contém a chave da conta de serviço.
Depois de concluir as etapas acima, o ADC encontrará suas credenciais automaticamente, conforme descrito na seção acima. O uso do ADC é recomendável porque requer menos códigos, que podem ser usados em ambientes diferentes.
Como transmitir credenciais usando códigos
Como alternativa, você pode optar por apontar explicitamente para o arquivo da sua conta de serviço no código, conforme mostrado no exemplo a seguir. É necessário instalar a biblioteca de cliente do Cloud Storage para executar o exemplo a seguir.
C#
Go
Java
Node.js
PHP
Python
Ruby
Solução de problemas de erros na API
Saiba mais sobre como resolver problemas de solicitações de API em Erros das APIs do Cloud.
A seguir
- Consulte nossas práticas recomendadas para gerenciar contas de serviço
- Saiba mais sobre práticas recomendadas para proteger contas de serviço
- Saiba mais sobre a autenticação em uma API do Google Cloud.
- Saiba mais sobre como se autenticar como usuário final
- Aprenda a usar chaves de API
Faça um teste
Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
Comece a usar gratuitamente