Criar e excluir chaves de contas de serviço

Nesta página, explicamos como criar e gerenciar chaves de conta de serviço com o console do Google Cloud, a CLI do Google Cloud, a API Identity and Access Management ou uma das bibliotecas de cliente do Google Cloud.

Antes de começar

• Enable the IAM API.

  Enable the API

• Configure a autenticação.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  C++

  Para usar os exemplos C++ desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  C#

  Para usar os exemplos .NET desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  Go

  Para usar os exemplos Go desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  Java

  Para usar os exemplos Java desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  Python

  Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  REST

  Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

• Entenda as credenciais da conta de serviço.

Funções exigidas

Para ter as permissões necessárias para fazer upload das chaves da conta de serviço, peça ao administrador que conceda a você o papel do IAM Administrador da chave da conta de serviço (roles/iam.serviceAccountKeyAdmin) no projeto ou a conta de serviço com as chaves que você quer gerenciar. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Para mais informações, consulte papéis de contas de serviço.

Dependendo da configuração da política da organização, talvez seja necessário permitir a criação de chaves de conta de serviço no projeto antes de criar uma chave.

Para receber as permissões necessárias para permitir que chaves da conta de serviço sejam criadas em um projeto, peça ao administrador que conceda a você os seguintes papéis do IAM na sua organização:

• Administrador de políticas da organização (roles/orgpolicy.policyAdmin)
• Leitor da organização (roles/resourcemanager.organizationViewer)
• Administrador de tags (roles/resourcemanager.tagAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para permitir que chaves das contas de serviço sejam criadas em um projeto. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Permitir a criação de chaves da conta de serviço

Antes de criar uma chave de conta de serviço, verifique se a restrição de política da organização iam.disableServiceAccountKeyCreation não está aplicada ao seu projeto. Se essa restrição for aplicada ao seu projeto, não será possível criar chaves de conta de serviço nele.

Recomendamos que você aplique essa restrição para a maioria dos projetos e isente apenas os projetos que realmente exigem chaves de contas de serviço. Para mais informações sobre métodos de autenticação alternativos, consulte Escolher o método de autenticação certo para o caso de uso.

Para isentar um projeto da restrição da política da organização iam.disableServiceAccountKeyCreation, peça a um administrador da política da organização para fazer o seguinte:

1. No nível da organização, crie uma chave de tag e um valor de tag que serão usados para definir se um projeto ou uma pasta será isento da política da organização. Recomendamos criar uma tag com a chave disableServiceAccountKeyCreation e os valores enforced e not_enforced.

   Para saber como criar chaves e valores de tag, consulte Como criar e definir uma nova tag.

2. Anexe a tag disableServiceAccountKeyCreation à organização e defina o valor como enforced. Todos os projetos ou pastas da organização herdam esse valor de tag, a menos que ele seja substituído por um valor de tag diferente.

   Para saber como anexar tags aos recursos, consulte Como anexar tags aos recursos.

3. Para cada projeto ou pasta que você quer isentar da política da organização, anexe a tag disableServiceAccountKeyCreation e defina-a com o valor not_enforced. Definir um valor de tag para um projeto ou uma pasta dessa maneira substitui o valor da tag herdado da organização.

4. Crie ou atualize a política da organização que impede a criação de chaves de contas de serviço para que ela não aplique a restrição a recursos isentos. Essa política precisa ter as seguintes regras:

   • Configure a restrição iam.disableServiceAccountKeyCreation para que não seja aplicada aos recursos com a tag disableServiceAccountKeyCreation: not_enforced. A condição nessa regra precisa ser semelhante a esta:

     resource.matchTag(\"ORGANIZATION_ID/disableServiceAccountKeyCreation\", \"not_enforced\")
     

   • Configure a restrição iam.disableServiceAccountKeyCreation para que seja aplicada a todos os outros recursos.

   Para saber como criar políticas da organização com condições de tag, consulte Como definir uma política da organização com tags.

Criar uma chave de conta de serviço

Para usar uma conta de serviço fora do Google Cloud, como em outras plataformas ou em 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. Quando você cria uma chave de conta de serviço, a parte pública é armazenada no Google Cloud, enquanto a parte privada fica disponível apenas para você. Para mais informações sobre pares de chaves públicas/privadas, consulte Chaves de conta de serviço.

É possível criar uma chave da conta de serviço usando o console do Google Cloud, a CLI gcloud, o método serviceAccounts.keys.create() ou uma das bibliotecas de cliente. Uma conta de serviço pode ter até 10 chaves.

Por padrão, as chaves da conta de serviço nunca expiram. É possível usar uma restrição de política da organização para especificar o período de validade da chave de conta de serviço. Para detalhes, consulte Prazos de validade das chaves gerenciadas pelo usuário.

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 Google Cloud.

{
  "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"
}

gcloud iam service-accounts keys create KEY_FILE \
    --iam-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com

created key [e44da1202f82f8f4bdd9d92bc412d1d8a837fa83] of type [json] as
[/usr/home/username/KEY_FILE] for
[SA_NAME@PROJECT_ID.iam.gserviceaccount.com]

{
  "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://oauth2.googleapis.com/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"
}

namespace iam = ::google::cloud::iam_admin_v1;
return [](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  auto response = client.CreateServiceAccountKey(
      name,
      google::iam::admin::v1::ServiceAccountPrivateKeyType::
          TYPE_GOOGLE_CREDENTIALS_FILE,
      google::iam::admin::v1::ServiceAccountKeyAlgorithm::KEY_ALG_RSA_2048);
  if (!response) throw std::move(response).status();
  std::cout << "ServiceAccountKey successfully created: "
            << response->DebugString() << "\n"
            << "Please save the key in a secure location, as they cannot "
               "be downloaded later\n";
  return response->name();
}

using System;
using System.Text;
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();

        // The PrivateKeyData field contains the base64-encoded service account key
        // in JSON format.
        // TODO(Developer): Save the below key (jsonKeyFile) to a secure location.
        //  You cannot download it later.
        byte[] valueBytes = System.Convert.FromBase64String(key.PrivateKeyData);
        string jsonKeyContent = Encoding.UTF8.GetString(valueBytes);

        Console.WriteLine("Key created successfully");
        return key;
    }
}

import (
	"context"
	// "encoding/base64"
	"fmt"
	"io"

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

// createKey creates a service account key.
func createKey(w io.Writer, serviceAccountEmail string) (*iam.ServiceAccountKey, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %w", 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: %w", err)
	}
	// The PrivateKeyData field contains the base64-encoded service account key
	// in JSON format.
	// TODO(Developer): Save the below key (jsonKeyFile) to a secure location.
	// You cannot download it later.
	// jsonKeyFile, _ := base64.StdEncoding.DecodeString(key.PrivateKeyData)
	fmt.Fprintf(w, "Key created successfully")
	return key, nil
}

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.gson.Gson;
import com.google.iam.admin.v1.CreateServiceAccountKeyRequest;
import com.google.iam.admin.v1.ServiceAccountKey;
import java.io.IOException;

public class CreateServiceAccountKey {

  public static void main(String[] args) throws IOException {
    // TODO(Developer): Replace the below variables before running.
    String projectId = "your-project-id";
    String serviceAccountName = "your-service-account-name";

    ServiceAccountKey key = createKey(projectId, serviceAccountName);
    Gson gson = new Gson();

    // System.out.println("Service account key: " + gson.toJson(key));
  }

  // Creates a key for a service account.
  public static ServiceAccountKey createKey(String projectId, String accountName)
          throws IOException {
    String email = String.format("%s@%s.iam.gserviceaccount.com", accountName, projectId);

    // Initialize client that will be used to send requests.
    // This client only needs to be created once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      CreateServiceAccountKeyRequest req = CreateServiceAccountKeyRequest.newBuilder()
              .setName(String.format("projects/%s/serviceAccounts/%s", projectId, email))
              .build();
      ServiceAccountKey createdKey = iamClient.createServiceAccountKey(req);
      System.out.println("Key created successfully");

      return createdKey;
    }
  }
}

from google.cloud import iam_admin_v1
from google.cloud.iam_admin_v1 import types


def create_key(project_id: str, account: str) -> types.ServiceAccountKey:
    """
    Creates a key for a service account.

    project_id: ID or number of the Google Cloud project you want to use.
    account: ID or email which is unique identifier of the service account.
    """

    iam_admin_client = iam_admin_v1.IAMClient()
    request = types.CreateServiceAccountKeyRequest()
    request.name = f"projects/{project_id}/serviceAccounts/{account}"

    key = iam_admin_client.create_service_account_key(request=request)

    # The private_key_data field contains the stringified service account key
    # in JSON format. You cannot download it again later.
    # If you want to get the value, you can do it in a following way:
    # import json
    # json_key_data = json.loads(key.private_key_data)
    # key_id = json_key_data["private_key_id"]

    return key

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys

{
  "keyAlgorithm": "KEY_ALGORITHM"
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL/keys/KEY_ID",
  "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE",
  "privateKeyData": "ENCODED_PRIVATE_KEY",
  "validAfterTime": "DATE",
  "validBeforeTime": "DATE",
  "keyAlgorithm": "KEY_ALG_RSA_2048"
}

echo 'ENCODED_PRIVATE_KEY' | base64 --decode > PATH

echo 'ENCODED_PRIVATE_KEY' | base64 --decode > PATH

Excluir uma chave da conta de serviço

A exclusão permanente de uma chave de conta de serviço impede que você use a chave para se autenticar com as APIs do Google.

Não é possível cancelar a exclusão de uma chave. Antes de excluir uma chave, recomendamos desativar a chave e aguardar até ter certeza de que ela não é mais necessária. Depois, exclua a chave.

Como prática recomendada, alterne as chaves da conta de serviço regularmente. Para saber mais sobre como alternar chaves de contas de serviço, consulte Rotação de chaves de conta de serviço.

gcloud iam service-accounts keys delete KEY_ID \
    --iam-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com

Deleted key [KEY_ID] for service account
[SA_NAME@PROJECT_ID.iam.gserviceaccount.com]

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  auto response = client.DeleteServiceAccountKey(name);
  if (!response.ok()) throw std::runtime_error(response.message());
  std::cout << "ServiceAccountKey successfully deleted.\n";
}

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);
    }
}

import (
	"context"
	"fmt"
	"io"

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

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

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

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.DeleteServiceAccountKeyRequest;
import com.google.iam.admin.v1.KeyName;
import java.io.IOException;

public class DeleteServiceAccountKey {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    String projectId = "your-project-id";
    String serviceAccountName = "my-service-account-name";
    String serviceAccountKeyId = "service-account-key-id";

    deleteKey(projectId, serviceAccountName, serviceAccountKeyId);
  }

  // Deletes a service account key.
  public static void deleteKey(String projectId, String accountName,
                               String serviceAccountKeyId) throws IOException {
    //Initialize client that will be used to send requests.
    //This client only needs to be created once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {

      //Construct the service account email.
      //You can modify the ".iam.gserviceaccount.com" to match the service account name in which
      //you want to delete the key.
      //See, https://cloud.google.com/iam/docs/creating-managing-service-account-keys#deleting

      String accountEmail = String.format("%s@%s.iam.gserviceaccount.com", accountName, projectId);

      String name = KeyName.of(projectId, accountEmail, serviceAccountKeyId).toString();

      DeleteServiceAccountKeyRequest request = DeleteServiceAccountKeyRequest.newBuilder()
              .setName(name)
              .build();

      // Then you can delete the key
      iamClient.deleteServiceAccountKey(request);

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

from google.cloud import iam_admin_v1
from google.cloud.iam_admin_v1 import types


def delete_key(project_id: str, account: str, key_id: str) -> None:
    """
    Deletes a key for a service account.

    project_id: ID or number of the Google Cloud project you want to use.
    account: ID or email which is unique identifier of the service account.
    key_id: unique ID of the key.
    """

    iam_admin_client = iam_admin_v1.IAMClient()
    request = types.DeleteServiceAccountKeyRequest()
    request.name = f"projects/{project_id}/serviceAccounts/{account}/keys/{key_id}"

    iam_admin_client.delete_service_account_key(request=request)
    print(f"Deleted key: {key_id}")

DELETE https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys/KEY_ID

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys/KEY_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys/KEY_ID" | Select-Object -Expand Content

{
}

A seguir

• Saiba como listar e receber chaves de conta de serviço.
• Saiba como fazer upload das chaves da sua conta de serviço público.
• Noções básicas sobre as práticas recomendadas para gerenciar chaves de conta de serviço.
• Saiba mais sobre alternativas às chaves de contas de serviço para autenticação.