Nesta página, explicamos como criar e gerenciar chaves de conta de serviço com o
Console do Google Cloud, a ferramenta de linha de comando gcloud
,
a API Identity and Access Management ou uma
das bibliotecas de cliente do Google Cloud.
Pré-requisitos para este guia
- Entender as contas de serviço.
- Instale a ferramenta
gcloud
Permissões necessárias
Para permitir que o usuário gerencie as chaves da conta de serviço, conceda a ele o papel de administrador da chave
da conta de serviço (roles/iam.serviceAccountKeyAdmin
). Para mais informações, consulte
Papéis de contas de serviço.
Os papéis básicos do IAM também contêm permissões para gerenciar as chaves da conta de serviço. Não conceda papéis básicos em um ambiente de produção. No entanto, é possível concedê-los em um ambiente de desenvolvimento ou teste.
Como criar chaves de conta de serviço
Para usar uma conta de serviço fora do Google Cloud, como em outras plataformas ou locais, é preciso primeiro estabelecer a identidade da conta de serviço. Pares de chaves públicas/privadas fornecem uma maneira segura de atingir essa meta.
É possível criar uma chave da conta de serviço usando o Console do Cloud, a gcloud
ferramenta, oserviceAccounts.keys.create()
método ou uma das bibliotecas de cliente.
Uma conta de serviço pode ter até 10 chaves.
Nos exemplos abaixo, sa-name
é o nome da conta de serviço e project-id
é o ID do projeto do Google Cloud. Você pode recuperar a string sa-name@project-id.iam.gserviceaccount.com
na página Contas de serviço no Console do Cloud.
Console
No Console do Cloud, acesse a página Contas de serviço:
Clique em Selecionar um projeto, escolha um projeto e clique em Abrir.
Encontre a linha da conta de serviço para a qual você quer criar uma chave. Nessa linha, clique no botão
e em Criar chave.Selecione um Tipo de chave e clique em Criar.
Clique em Criar para fazer o download de um arquivo de chave da conta de serviço. Após fazer o download do arquivo de chave, não será possível fazer o download novamente.
Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. É possível mover e renomear esse arquivo como você quiser.
gcloud
Execute o comando gcloud iam service-accounts keys create
para criar chaves de conta de serviço.
Comando:
gcloud iam service-accounts keys create ~/key.json \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Saída:
created key [e44da1202f82f8f4bdd9d92bc412d1d8a837fa83] of type [json] as [/usr/home/username/key.json] for [sa-name@project-id.iam.gserviceaccount.com]
Agora o download do arquivo de chave da conta de serviço é feito em sua máquina. Após fazer o download do arquivo de chave, não será possível fazer o download novamente.
Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. É possível mover e renomear esse arquivo como quiser.
REST
O
método
projects.serviceAccounts.keys.create
cria uma chave para uma conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
project-id
: é o ID do projeto do Google Cloud.sa-name
: é o nome da conta de serviço para a qual você quer criar uma chave.private-key-type
: opcional. O formato de saída da chave privada. O valor padrão éTYPE_GOOGLE_CREDENTIALS_FILE
, que é um arquivo de chave JSON codificado em base64. Para ver uma lista de todos os valores possíveis, consulte a referência deServiceAccountPrivateKeyType
.key-algorithm
: opcional. O algoritmo de chave a ser usado na chave. O padrão, que está sujeito a alterações, é uma chave RSA de 2.048 bits. Para ver uma lista de todos os valores possíveis, consulte a referência deServiceAccountKeyAlgorithm
.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys
Corpo JSON da solicitação:
{ "privateKeyType": "private-key-type", "keyAlgorithm": "key-algorithm" }
Para enviar a solicitação, expanda uma destas opções:
A resposta contém uma chave para a conta de serviço, por exemplo:
{ "name":"projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c", "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE", "privateKeyData":"MIIJqAIB . . .", "validAfterTime": "2020-05-17T18:48:27Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }
Armazene os dados principais com segurança, porque eles podem ser usados para fazer autenticação como sua conta de serviço.
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Java
Antes de testar este exemplo, siga as instruções de configuração do Java no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Java.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Observe que o privateKeyData
retornado é uma representação de string codificada em base64 do valor TYPE_GOOGLE_CREDENTIALS_FILE
(chave/credenciais JSON ou P12).
Quando você cria uma chave, o novo par de chaves públicas/particulares é gerado e o download dele é feito para sua máquina. Ele serve como a única cópia da chave particular. Você é responsável por armazenar a chave privada com segurança. Anote a localização dela e certifique-se de que o aplicativo possa acessá-la. Ele precisa da chave para fazer chamadas de API autenticadas.
O formato da chave varia dependendo de como ela é gerada. Chaves criadas usando o Console do Cloud ou a ferramenta de linha de comando gcloud
tem esta aparência:
{ "type": "service_account", "project_id": "project-id", "private_key_id": "key-id", "private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n", "client_email": "service-account-email", "client_id": "client-id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://accounts.google.com/o/oauth2/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email" }
Enquanto isso, as chaves geradas com a API REST ou as bibliotecas de clientes têm o seguinte formato:
{ "name": "projects/project-id/serviceAccounts/service-account-email/keys/key-id", "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE", "privateKeyData": "private-key", "validAfterTime": "date", "validBeforeTime": "date", "keyAlgorithm": "KEY_ALG_RSA_2048" }
Observe mais uma vez que o privateKeyData
retornado é uma representação de string codificada em base64 do valor TYPE_GOOGLE_CREDENTIALS_FILE
(chave/credenciais JSON ou P12). É possível armazenar o privateKeyData
de base64 em um arquivo com a extensão apropriada (.p12
ou .json
) e usá-lo como entrada para bibliotecas de clienteou pelo comando gcloud auth activate-service-account
.
Como a formatação difere entre cada método, é mais fácil gerar uma chave com o mesmo método que você planeja usar ao fazer futuras chamadas de API. Por exemplo, se você estiver usando gcloud
, também gere sua chave usando gcloud
. Se quiser usar uma chave para um método gerado utilizando um método diferente (por exemplo, usar uma chave gerada por REST com gcloud
), será preciso editar a chave para corresponder ao formato apropriado.
O Google garante que todas as chaves públicas para todas as contas de serviço sejam publicamente acessíveis por qualquer pessoa e fiquem disponíveis para verificar assinaturas criadas com a chave privada. A chave pública está publicamente acessível nos seguintes URLs:
- Certificado x.509: https://www.googleapis.com/service_accounts/v1/metadata/x509/sa-name@project-id.iam.gserviceaccount.com
- Chave da Web JSON (JWK): https://www.googleapis.com/service_accounts/v1/jwk/sa-name@project-id.iam.gserviceaccount.com
- Ponto de extremidade bruto: https://www.googleapis.com/service_accounts/v1/metadata/raw/sa-name@project-id.iam.gserviceaccount.com
Como listar chaves de conta de serviço
É possível listar as chaves da conta de serviço de uma conta de serviço usando o Console do Cloud, a ferramenta gcloud
, o método serviceAccount.keys.list()
ou uma das bibliotecas de cliente.
O método serviceAccount.keys.list()
normalmente é usado para auditar contas de serviço e chaves ou para criar ferramentas personalizadas a fim de gerenciar contas de serviço.
Para descobrir a que projeto sua chave pertence, faça o download da chave como um arquivo JSON e procure nesse arquivo.
É possível que você veja chaves que você não criou listadas. Essas são chaves gerenciadas pelo Google Cloud usadas pelos serviços do Google Cloud, como o App Engine e o Compute Engine. Para saber mais sobre a diferença entre chaves gerenciadas pelo usuário e pelo Google Cloud, consulte Noções básicas sobre as contas de serviço.
Console
No Console do Cloud, acesse a página Contas de serviço:
Clique em Selecionar um projeto, escolha um projeto e clique em Abrir. O console lista todas as contas de serviço do projeto e as chaves correspondentes.
gcloud
Execute o comando gcloud iam service-accounts keys list
para listar as chaves da conta de serviço.
Comando:
gcloud iam service-accounts keys list \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Saída:
KEY_ID | CREATED_AT | EXPIRES_AT |
8e6e3936d7024646f8ceb39792006c07f4a9760c | 2021-01-01T21:01:42Z | 9999-12-31T23:59:59Z |
937c98f870f5c8db970af527aa3c12fd88b1c20a | 2021-01-01T20:55:40Z | 9999-12-31T23:59:59Z |
REST
O
método
projects.serviceAccounts.keys.list
lista todas as chaves de uma conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
project-id
: o ID do projeto do Google Cloud.sa-name
: o nome da conta de serviço cujas chaves você quer listar.key-types
: opcional. Uma lista separada por vírgulas dos tipos de chave que você quer incluir na resposta. O tipo de chave indica se uma chave é gerenciada pelo usuário (USER_MANAGED
) ou pelo sistema (SYSTEM_MANAGED
). Se deixado em branco, todas as chaves são retornadas.
Método HTTP e URL:
GET https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys?keyTypes=key-types
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "keys": [ { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c", "validAfterTime": "2020-03-04T17:39:47Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }, { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8", "validAfterTime": "2020-03-31T23:50:09Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }, { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e", "validAfterTime": "2020-05-17T18:58:13Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" } ] }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Java
Antes de testar este exemplo, siga as instruções de configuração do Java no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Java.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Como encontrar uma chave da conta de serviço
Só é possível visualizar os dados da chave privada para uma chave da conta de serviço quando ela é criada pela primeira vez.
Encontre informações básicas sobre uma chave, como ID, algoritmo e dados de chave pública, com o método da API REST projects.serviceAccounts.keys.get()
. Não é possível usar o Console do Cloud ou a ferramenta de linha de comando gcloud
.
Como fazer upload de chaves públicas para contas de serviço
Você pode fazer upload da parte da chave pública de um par de chaves gerenciadas pelo usuário para uma conta de serviço. Depois de fazer upload da chave pública, ela ficará permanentemente associada à conta de serviço e será usada da mesma forma que qualquer outra chave da conta de serviço gerenciada pelo usuário. Para desativar a capacidade de fazer upload de chaves para seu projeto, consulte como restringir o upload de chave de conta de serviço.
Se você preferir usar um par de chaves gerenciado pelo usuário em vez de um par de chaves gerenciado pelo Google, não deixe de mantê-lo e alterná-lo.
A chave enviada precisa ser uma chave pública RSA, encapsulada em um certificado X.509 v3 e codificada em base64. É possível usar ferramentas como o OpenSSL para gerar uma chave e um certificado nesse formato. Por exemplo, o comando a seguir gera um par de chaves RSA de 2.048 bits e encapsula a chave pública em um certificado autoassinado válido por 365 dias:
openssl req -x509 -nodes -newkey rsa:2048 -days 365 \
-keyout /path/to/private_key.pem \
-out /path/to/public_key.pem \
-subj "/CN=unused"
Em seguida, faça o upload do arquivo public_key.pem
como a chave pública de uma conta
de serviço.
gcloud
Execute o comando gcloud iam service-accounts keys upload
para fazer upload de uma chave pública a fim de assinar chaves de contas de serviço.
Comando:
gcloud iam service-accounts keys upload /path/to/public_key.pem \ --iam-account sa-name@project-id.iam.gserviceaccount.com
A saída contém um identificador exclusivo para a chave enviada:
Name: projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0
Para determinar se o comando foi bem-sucedido, execute o comando gcloud iam service-accounts keys list
:
gcloud iam service-accounts keys list \ --iam-account sa-name@project-id.iam.gserviceaccount.com
A saída terá o mesmo identificador exclusivo que foi retornado após a criação da chave:
KEY_ID | CREATED_AT | EXPIRES_AT |
c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0 | 2019-06-26T21:01:42Z | 9999-12-31T23:59:59Z |
REST
O
método
projects.serviceAccounts.keys.upload
faz upload da chave pública de um par de chaves gerenciado pelo usuário e adiciona essa chave
à conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
project-id
: é o ID do projeto do Google Cloud.sa-name
: o nome da conta de serviço à qual associar a chave.public-key-data
: os dados da chave pública do par de chaves. Precisa ser uma chave pública RSA encapsulada em um certificado X.509 v3. Codifique os dados da chave pública em base64, incluindo a primeira linha,-----BEGIN CERTIFICATE-----
, e a última,-----END CERTIFICATE-----
.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys:upload
Corpo JSON da solicitação:
{ "publicKeyData": "public-key-data" }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0", "validAfterTime": "2020-05-17T19:31:19Z", "validBeforeTime": "2021-05-17T19:31:19Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "USER_PROVIDED", "keyType": "USER_MANAGED" }
Como excluir chaves de contas de serviço
Exclua uma chave de conta de serviço usando o Console do Cloud, a ferramenta gcloud
, o método serviceAccount.keys.delete()
ou uma das bibliotecas de cliente.
Se você excluir uma chave, não será mais possível usá-la para acessar os recursos do
Google Cloud pelo aplicativo. Uma prática recomendada de segurança é alternar as chaves da conta de serviço regularmente. Para fazer isso, crie uma chave, altere os aplicativos para que eles a usem e exclua a chave antiga. Use o método serviceAccount.keys.create()
e o método serviceAccount.keys.delete()
juntos para automatizar a alternância.
Console
No Console do Cloud, acesse a página Contas de serviço:
Clique em Selecionar um projeto, escolha um projeto e clique em Abrir. O console lista todas as contas de serviço do projeto e as chaves correspondentes.
Encontre a linha da conta de serviço para a qual você quer criar uma chave. Nessa linha, clique no botão
e clique em Editar.Na lista de chaves, clique em Excluir
para todas que quiser remover.
gcloud
Execute o comando gcloud iam service-accounts keys delete
para excluir as chaves da conta de serviço.
Comando:
gcloud iam service-accounts keys delete key-id \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Saída:
Deleted key [8e6e3936d7024646f8ceb39792006c07f4a9760c] for service account [sa-name@project-id.iam.gserviceaccount.com]
REST
O
método
projects.serviceAccounts.keys.delete
exclui uma chave de conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
project-id
: é o ID do projeto do Google Cloud.sa-name
: o nome da conta de serviço cuja chave você quer excluir.key-id
: o ID da chave que você quer excluir.
Método HTTP e URL:
DELETE https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys/key-id
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Java
Antes de testar este exemplo, siga as instruções de configuração do Java no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Java.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.