Como criar e gerenciar chaves de contas 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

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.

Para mais informações, consulte a lista de funções de Contas de serviço.

Como criar chaves de conta de serviço

Para usar uma conta de serviço de fora do GCP, como em outras plataformas ou no local, é 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 de conta de serviço usando o Console do GCP, a ferramenta gcloud, o método serviceAccounts.keys.create() (links em inglês) ou uma das bibliotecas de cliente.

Nos exemplos abaixo, [SA-NAME] é o nome da conta de serviço, e [PROJECT-ID] é o ID 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

  1. Abra a página IAM e Admin no Console do GCP.

    Abrir a página IAM e Admin

  2. Selecione o projeto e clique em Continuar.

  3. Na navegação à esquerda, clique em Contas de serviço.

  4. 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.

  5. Selecione um Tipo de chave e clique em Criar.

COMANDO GCLOUD

Execute o comando gcloud iam service-accounts keys create (link em inglês) 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#.


using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class ServiceAccountKeys
{
    public static ServiceAccountKey CreateKey(string serviceAccountEmail)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var key = service.Projects.ServiceAccounts.Keys.Create(
            new CreateServiceAccountKeyRequest(),
            "projects/-/serviceAccounts/" + serviceAccountEmail)
            .Execute();
        Console.WriteLine("Created key: " + key.Name);
        return key;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go 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 Go.

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// createKey creates a service account key.
func createKey(w io.Writer, serviceAccountEmail string) (*iam.ServiceAccountKey, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/-/serviceAccounts/" + serviceAccountEmail
	request := &iam.CreateServiceAccountKeyRequest{}
	key, err := service.Projects.ServiceAccounts.Keys.Create(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.Keys.Create: %v", err)
	}
	fmt.Fprintf(w, "Created key: %v", key.Name)
	return key, nil
}

Java

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 Cloud IAM Java.

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.

import os

from google.oauth2 import service_account
import googleapiclient.discovery

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

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ['GOOGLE_APPLICATION_CREDENTIALS'],
        scopes=['https://www.googleapis.com/auth/cloud-platform'])

    service = googleapiclient.discovery.build(
        'iam', 'v1', credentials=credentials)

    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 do valor TYPE_GOOGLE_CREDENTIALS_FILE (chave/credenciais 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"
}

Observe novamente que o privateKeyData retornado é uma representação de cadeia codificada em base64 do valor TYPE_GOOGLE_CREDENTIALS_FILE (chave/credenciais JSON ou P12).

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() (link em inglês) 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

  1. Abra a página IAM e Admin no Console do GCP.

    Abrir a página IAM e Admin

  2. Selecione o projeto e clique em Continuar.

  3. 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

API REST

Chame serviceAccount.keys.list() para listar as chaves de uma conta de serviço.

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#

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#.


using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class ServiceAccountKeys
{
    public static IList<ServiceAccountKey> ListKeys(string serviceAccountEmail)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.ServiceAccounts.Keys
            .List($"projects/-/serviceAccounts/{serviceAccountEmail}")
            .Execute();
        foreach (ServiceAccountKey key in response.Keys)
        {
            Console.WriteLine("Key: " + key.Name);
        }
        return response.Keys;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go 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 Go.

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// listKey lists a service account's keys.
func listKeys(w io.Writer, serviceAccountEmail string) ([]*iam.ServiceAccountKey, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/-/serviceAccounts/" + serviceAccountEmail
	response, err := service.Projects.ServiceAccounts.Keys.List(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.Keys.List: %v", err)
	}
	for _, key := range response.Keys {
		fmt.Fprintf(w, "Listing key: %v", key.Name)
	}
	return response.Keys, nil
}

Java

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 Cloud IAM Java.

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

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.

import os

from google.oauth2 import service_account
import googleapiclient.discovery

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

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ['GOOGLE_APPLICATION_CREDENTIALS'],
        scopes=['https://www.googleapis.com/auth/cloud-platform'])

    service = googleapiclient.discovery.build(
        'iam', 'v1', credentials=credentials)

    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() (link em inglês) 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() (link em inglês) 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

  1. Abra a página IAM e Admin no Console do GCP.

    Abrir a página IAM e Admin

  2. Selecione o projeto e clique em Continuar.

  3. Na navegação à esquerda, clique em Contas de serviço. Todas as contas de serviço e chaves correspondentes são listadas.

  4. Clique no e-mail da conta de serviço desejada para visualizar as chaves dela.

  5. 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 (link em inglês) 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#

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#.


using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class ServiceAccountKeys
{
    public static void DeleteKey(string fullKeyName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.ServiceAccounts.Keys.Delete(fullKeyName).Execute();
        Console.WriteLine("Deleted key: " + fullKeyName);
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go 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 Go.

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// deleteKey deletes a service account key.
func deleteKey(w io.Writer, fullKeyName string) error {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return fmt.Errorf("iam.New: %v", err)
	}

	_, err = service.Projects.ServiceAccounts.Keys.Delete(fullKeyName).Do()
	if err != nil {
		return fmt.Errorf("Projects.ServiceAccounts.Keys.Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted key: %v", fullKeyName)
	return nil
}

Java

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 Cloud IAM Java.

public void deleteKey(String fullKeyName) throws IOException {

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

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

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.

import os

from google.oauth2 import service_account
import googleapiclient.discovery

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

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ['GOOGLE_APPLICATION_CREDENTIALS'],
        scopes=['https://www.googleapis.com/auth/cloud-platform'])

    service = googleapiclient.discovery.build(
        'iam', 'v1', credentials=credentials)

    service.projects().serviceAccounts().keys().delete(
        name=full_key_name).execute()

    print('Deleted key: ' + full_key_name)

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Cloud IAM