Como criar e gerenciar chaves de conta de serviço

Nesta página, explicamos como criar e gerenciar as chaves da conta de serviço usando o Console do Google Cloud Platform, a ferramenta de linha de comando gcloud, a API Cloud Identity and Access Management ou uma das bibliotecas de cliente do Google Cloud.

Pré-requisitos para este guia

Entender as contas de serviço.
Instalar 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 Administrador da chave da conta de serviço (roles/iam.serviceAccountKeyAdmin). Os papéis primários do Cloud IAM também contêm permissões para gerenciar as chaves da conta de serviço, mas recomendamos que você conceda este papel para evitar o acesso desnecessário a outros recursos do GCP.

Consulte o tópico Papéis da conta de serviço para saber mais sobre os papéis relacionados a contas de serviço.

Como criar chaves de conta de serviço

Para usar uma conta de serviço fora do Google Cloud Platform, em outras plataformas ou no local, estabeleça a identidade da conta de serviço. Isso pode ser feito com os pares de chave pública/privada.

É possível criar uma chave da conta de serviço usando o Console do GCP, a ferramenta gcloud, o método serviceAccounts.keys.create() ou uma das bibliotecas de cliente.

Nos exemplos abaixo, [SA-NAME] é o nome da conta de serviço, e [PROJECT-ID] é o código do projeto do Google Cloud Platform. Recupere a string [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com na página Contas de serviço no Console do GCP.

Console

Abra a página IAM e Admin no Console do GCP.
Abrir a página IAM e Admin
Selecione o projeto e clique em Continuar.
Na navegação à esquerda, clique em Contas de serviço.
Procure a conta de serviço em que você quer criar a chave, clique no botão Mais more_vert na linha correspondente e selecione Criar chave.
Selecione um Tipo de chave e clique em Criar.

COMANDO GCLOUD

Execute o comando gcloud iam service-accounts keys create para criar as chaves da 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]

REST API

Solicitação:

POST https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys

Resposta:

{
    "name":"projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
    "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE",
    "privateKeyData":"MIIJqAIB . . .",
    "validBeforeTime": "2028-05-08T21:00:00Z",
    "validAfterTime": "2016-01-25T18:38:09.000Z",
    "keyAlgorithm": "KEY_ALG_RSA_2048"
}

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

public static ServiceAccountKey CreateKey(string serviceAccountEmail)
{
    ServiceAccountKey key = s_service.Projects.ServiceAccounts.Keys.Create(
        new CreateServiceAccountKeyRequest(),
        "projects/-/serviceAccounts/" + serviceAccountEmail)
        .Execute();

    Console.WriteLine("Created key: " + key.Name);
    return key;
}

Java

Ver no GitHub Feedback

public ServiceAccountKey createKey(String serviceAccountEmail) throws IOException {

  ServiceAccountKey key =
      service
          .projects()
          .serviceAccounts()
          .keys()
          .create(
              "projects/-/serviceAccounts/" + serviceAccountEmail,
              new CreateServiceAccountKeyRequest())
          .execute();

  System.out.println("Created key: " + key.getName());
  return key;
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def create_key(service_account_email):
    """Creates a key for a service account."""

    # pylint: disable=no-member
    key = service.projects().serviceAccounts().keys().create(
        name='projects/-/serviceAccounts/' + service_account_email, body={}
        ).execute()

    print('Created key: ' + key['name'])

O privateKeyData retornado é uma representação de string codificada em base64 das credenciais/chave de JSON ou P12.

Quando você cria uma chave, o novo par de chave pública/particular é 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.

Pode levar até 60 segundos para que seja possível usar uma chave recém-criada na autenticação. Caso ocorram falhas na autenticação logo após a criação de uma nova chave, aguarde 60 segundos antes de tentar novamente.

O formato da chave varia dependendo de como ela é gerada. As chaves criadas usando o Console do GCP ou a ferramenta de linha de comando gcloud têm a seguinte aparência:

{
"type": "service_account",
"project_id": "[PROJECT-ID]",
"private_key_id": "[KEY-ID]"
"private_key": "-----BEGIN PRIVATE KEY-----\n[PRIVATE-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"
}

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, caso esteja usando o gcloud, também gere sua chave com o gcloud. Se você quiser usar uma chave em um método diferente do qual ela foi criada (por exemplo, aplicar uma chave gerada pelo REST usando o gcloud), será necessário editá-la 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 usando o Console do GCP, a ferramenta gcloud, o método serviceAccount.keys.list() ou uma das bibliotecas de cliente.

O método serviceAccount.keys.list() é usado para auditar chaves e contas de serviço ou criar ferramentas personalizadas para gerenciar essas contas.

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 as chaves gerenciadas pelo GCP e usadas por serviços como o App Engine e o Compute Engine. Para saber mais sobre a diferença entre as chaves gerenciadas pelo usuário e pelo GCP, consulte Noções básicas sobre contas de serviço.

Console

Abra a página IAM e Admin no Console do GCP.
Abrir a página IAM e Admin
Selecione o projeto e clique em Continuar.
Na navegação à esquerda, clique em Contas de serviço. Todas as contas de serviço e chaves correspondentes são listadas.

COMANDO 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	2016-01-26T21:01:42.000Z	2026-01-23T21:01:42.000Z
937c98f870f5c8db970af527aa3c12fd88b1c20a	2016-01-26T20:55:40.000Z	2026-01-23T20:55:40.000Z

REST API

Solicitação:

POST https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys

Resposta:

{
    "keys": [
    {
        "name": "projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
        "validAfterTime": "2016-01-25T18:38:09.000Z",
        "validBeforeTime": "2026-01-22T18:38:09.000Z",
        "keyAlgorithm": "KEY_ALG_RSA_2048"
    },
    {
        "name": "projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8",
        "validAfterTime": "2016-01-25T13:43:27.000Z",
        "validBeforeTime": "2016-01-26T13:43:27.000Z",
        "keyAlgorithm": "KEY_ALG_RSA_2048"
    },
    {
        "name": "projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e",
        "validAfterTime": "2016-01-26T13:28:27.000Z",
        "validBeforeTime": "2016-01-27T13:28:27.000Z",
        "keyAlgorithm": "KEY_ALG_RSA_2048"
    }]
}

C#

Ver no GitHub Feedback

public static IList<ServiceAccountKey> ListKeys(string serviceAccountEmail)
{
    IList<ServiceAccountKey> keys = s_service.Projects.ServiceAccounts.Keys
        .List($"projects/-/serviceAccounts/{serviceAccountEmail}")
        .Execute().Keys;

    foreach (ServiceAccountKey key in keys)
    {
        Console.WriteLine("Key: " + key.Name);
    }
    return keys;
}

Java

Ver no GitHub Feedback

public List<ServiceAccountKey> listKeys(String serviceAccountEmail) throws IOException {

  List<ServiceAccountKey> keys =
      service
          .projects()
          .serviceAccounts()
          .keys()
          .list("projects/-/serviceAccounts/" + serviceAccountEmail)
          .execute()
          .getKeys();

  for (ServiceAccountKey key : keys) {
    System.out.println("Key: " + key.getName());
  }
  return keys;
}

Python

Ver no GitHub Feedback

def list_keys(service_account_email):
    """Lists all keys for a service account."""

    # pylint: disable=no-member
    keys = service.projects().serviceAccounts().keys().list(
        name='projects/-/serviceAccounts/' + service_account_email).execute()

    for key in keys['keys']:
        print('Key: ' + key['name'])

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.

Para ver as informações básicas de uma chave como código, algoritmo e dados de chave pública, use o método projects.serviceAccounts.keys.get() da API REST. Não é possível usar o Console do GCP ou a ferramenta de linha de comando gcloud.

Como excluir chaves de contas de serviço

É possível excluir uma chave da conta de serviço usando o Console do GCP, 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 Cloud Platform pelo aplicativo. Uma prática recomendada de segurança é trocar as chaves da conta de serviço regularmente. Para fazer isso, crie uma nova chave, alterne os aplicativos para que usem essa chave e exclua a chave antiga. Use o método serviceAccount.keys.create() e serviceAccount.keys.delete() juntos para automatizar a troca.

Console

Abra a página IAM e Admin no Console do GCP.
Abrir a página IAM e Admin
Selecione o projeto e clique em Continuar.
Na navegação à esquerda, clique em Contas de serviço. Todas as contas de serviço e chaves correspondentes são listadas.
Clique no e-mail da conta de serviço desejada para visualizar as chaves dela.
Na lista de chaves, clique em Excluir delete para aquelas que você quer remover.

COMANDO 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 API

Solicitação:

DELETE https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys/[KEY-ID]

C#

Ver no GitHub Feedback

public static void DeleteKey(string fullKeyName)
{
    s_service.Projects.ServiceAccounts.Keys.Delete(fullKeyName).Execute();
    Console.WriteLine("Deleted key: " + fullKeyName);
}

Java

Ver no GitHub Feedback

public void deleteKey(String fullKeyName) throws IOException {

  service.projects().serviceAccounts().keys().delete(fullKeyName).execute();

  System.out.println("Deleted key: " + fullKeyName);
}

Python

Ver no GitHub Feedback

def delete_key(full_key_name):
    """Deletes a service account key."""

    # pylint: disable=no-member
    service.projects().serviceAccounts().keys().delete(
        name=full_key_name).execute()

    print('Deleted key: ' + full_key_name)

Pré-requisitos para este guia

Permissões necessárias

Como criar chaves de conta de serviço

Console

COMANDO GCLOUD

REST API

C#

Java

Python

Como listar chaves de conta de serviço

Console

COMANDO GCLOUD

REST API

C#

Java

Python

Como encontrar uma chave da conta de serviço

Como excluir chaves de contas de serviço

Console

COMANDO GCLOUD

REST API

C#

Java

Python

Enviar comentários sobre…