Listar e editar contas de serviço

Nesta página, explicamos como listar e editar contas de serviço usando a API Identity and Access Management (IAM), o console do Google Cloud e a ferramenta de linha de comando gcloud.

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

    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.

    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 contas de serviço do IAM

Funções exigidas

Para receber as permissões necessárias para gerenciar contas de serviço, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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 saber mais sobre esses papéis, consulte Papéis de contas de serviço.

Os papéis básicos do IAM também contêm permissões para gerenciar as contas de serviço. Não conceda papéis básicos em um ambiente de produção, recomendamos que você faça isso em um ambiente de desenvolvimento ou teste.

Como listar contas de serviço

É possível listar as contas de serviço gerenciadas pelo usuário em um projeto para ajudar a auditar contas de serviço e chaves ou como parte de uma ferramenta personalizada para gerenciar contas de serviço.

Não é possível listar os agentes de serviço que podem aparecer nos registros de auditoria e políticas do projeto. Os agentes de serviço não estão localizados no projeto e não é possível acessá-los diretamente.

Console

  1. No console do Google Cloud, acesse a página Contas de serviço.

    Acesse as Contas de serviço

  2. Selecione um projeto.

    A página Contas de serviço lista todas as contas de serviço gerenciadas pelo usuário no projeto selecionado.

gcloud

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

  2. Execute o comando gcloud iam service-accounts list para listar todas as contas de serviço em um projeto.

    Comando:

    gcloud iam service-accounts list

    A saída é a lista de todas as contas de serviço gerenciadas pelo usuário no projeto:

    NAME                    EMAIL
    SA_DISPLAY_NAME_1    SA_NAME_1@PROJECT_ID.iam.gserviceaccount.com
    SA_DISPLAY_NAME_2    SA_NAME_2@PROJECT_ID.iam.gserviceaccount.com
    

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API C++ do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& project_id) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  for (auto& sa : client.ListServiceAccounts("projects/" + project_id)) {
    if (!sa) throw std::move(sa).status();
    std::cout << "ServiceAccount successfully retrieved: " << sa->name()
              << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No service accounts found in project: " << project_id
              << "\n";
  }
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API C# do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.


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 ServiceAccounts
{
    public static IList<ServiceAccount> ListServiceAccounts(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.ServiceAccounts.List(
            "projects/" + projectId).Execute();
        foreach (ServiceAccount account in response.Accounts)
        {
            Console.WriteLine("Name: " + account.Name);
            Console.WriteLine("Display Name: " + account.DisplayName);
            Console.WriteLine("Email: " + account.Email);
            Console.WriteLine();
        }
        return response.Accounts;
    }
}

Go

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Go do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

import (
	"context"
	"fmt"
	"io"

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

// listServiceAccounts lists a project's service accounts.
func listServiceAccounts(w io.Writer, projectID string) ([]*iam.ServiceAccount, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %w", err)
	}

	response, err := service.Projects.ServiceAccounts.List("projects/" + projectID).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.List: %w", err)
	}
	for _, account := range response.Accounts {
		fmt.Fprintf(w, "Listing service account: %v\n", account.Name)
	}
	return response.Accounts, nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Java do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.


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

public class ListServiceAccounts {

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

    listServiceAccounts(projectId);
  }

  // Lists all service accounts for the current project.
  public static IAMClient.ListServiceAccountsPagedResponse listServiceAccounts(String projectId)
          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()) {
      IAMClient.ListServiceAccountsPagedResponse response =
              iamClient.listServiceAccounts(String.format("projects/%s", projectId));

      for (ServiceAccount account : response.iterateAll()) {
        System.out.println("Name: " + account.getName());
        System.out.println("Display name: " + account.getDisplayName());
        System.out.println("Email: " + account.getEmail() + "\n");
      }

      return response;
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Python do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

from typing import List

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


def list_service_accounts(project_id: str) -> List[iam_admin_v1.ServiceAccount]:
    """
    Get list of project service accounts.

    project_id: ID or number of the Google Cloud project you want to use.
    """

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

    accounts = iam_admin_client.list_service_accounts(request=request)
    return accounts.accounts

REST

O método serviceAccounts.list lista todas as contas de serviço gerenciadas pelo usuário no projeto.

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. Os IDs do projeto são strings alfanuméricas, como my-project.

Método HTTP e URL:

GET https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "accounts": [
    {
      "name": "projects/my-project/serviceAccounts/sa-1@my-project.iam.gserviceaccount.com",
      "projectId": "my-project",
      "uniqueId": "123456789012345678901",
      "email": "sa-1@my-project.iam.gserviceaccount.com",
      "description": "My first service account",
      "displayName": "Service account 1",
      "etag": "BwUpTsLVUkQ=",
      "oauth2ClientId": "987654321098765432109"
    },
    {
      "name": "projects/my-project/serviceAccounts/sa-2@my-project.iam.gserviceaccount.com",
      "projectId": "my-project",
      "uniqueId": "234567890123456789012",
      "email": "sa-2@my-project.iam.gserviceaccount.com",
      "description": "My second service account",
      "displayName": "Service account 2",
      "etag": "UkQpTwBVUsL=",
      "oauth2ClientId": "876543210987654321098"
    }
  ]
}

Editar uma conta de serviço

O nome de exibição (nome intuitivo) e a descrição de uma conta de serviço geralmente são usados para capturar mais informações sobre ela, como o objetivo da conta de serviço ou uma pessoa de contato dela.

Console

  1. No console do Google Cloud, acesse a página Contas de serviço.

    Acesse as Contas de serviço

  2. Selecione um projeto.

  3. Clique no endereço de e-mail da conta de serviço que você quer renomear.

  4. Insira o novo nome na caixa Nome e clique em Salvar.

gcloud

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

  2. Execute o comando gcloud iam service-accounts update para atualizar uma conta de serviço.

    Comando:

    gcloud iam service-accounts update 
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    --description="UPDATED_SA_DESCRIPTION"
    --display-name="UPDATED_DISPLAY_NAME"

    A saída é a conta de serviço renomeada:

    description: UPDATED_SA_DESCRIPTION
    displayName: UPDATED_DISPLAY_NAME
    name: projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API C++ do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name, std::string const& display_name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::PatchServiceAccountRequest request;
  google::iam::admin::v1::ServiceAccount service_account;
  service_account.set_name(name);
  service_account.set_display_name(display_name);
  google::protobuf::FieldMask update_mask;
  *update_mask.add_paths() = "display_name";
  *request.mutable_service_account() = service_account;
  *request.mutable_update_mask() = update_mask;
  auto response = client.PatchServiceAccount(request);
  if (!response) throw std::move(response).status();
  std::cout << "ServiceAccount successfully updated: "
            << response->DebugString() << "\n";
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API C# do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.


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

public partial class ServiceAccounts
{
    public static ServiceAccount RenameServiceAccount(string email,
        string newDisplayName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        // First, get a ServiceAccount using List() or Get().
        string resource = "projects/-/serviceAccounts/" + email;
        var serviceAccount = service.Projects.ServiceAccounts.Get(resource)
            .Execute();
        // Then you can update the display name.
        serviceAccount.DisplayName = newDisplayName;
        serviceAccount = service.Projects.ServiceAccounts.Update(
            serviceAccount, resource).Execute();
        Console.WriteLine($"Updated display name for {serviceAccount.Email} " +
            "to: " + serviceAccount.DisplayName);
        return serviceAccount;
    }
}

Go

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Go do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

import (
	"context"
	"fmt"
	"io"

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

// renameServiceAccount renames a service account.
func renameServiceAccount(w io.Writer, email, newDisplayName string) (*iam.ServiceAccount, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %w", err)
	}

	// First, get a ServiceAccount using List() or Get().
	resource := "projects/-/serviceAccounts/" + email
	serviceAccount, err := service.Projects.ServiceAccounts.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.Get: %w", err)
	}
	// Then you can update the display name.
	serviceAccount.DisplayName = newDisplayName
	serviceAccount, err = service.Projects.ServiceAccounts.Update(resource, serviceAccount).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.Update: %w", err)
	}

	fmt.Fprintf(w, "Updated service account: %v", serviceAccount.Email)
	return serviceAccount, nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Java do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.


import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.GetServiceAccountRequest;
import com.google.iam.admin.v1.PatchServiceAccountRequest;
import com.google.iam.admin.v1.ServiceAccount;
import com.google.iam.admin.v1.ServiceAccountName;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class RenameServiceAccount {
  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 displayName = "your-new-display-name";

    renameServiceAccount(projectId, serviceAccountName, displayName);
  }

  // Changes a service account's display name.
  public static ServiceAccount renameServiceAccount(String projectId, String serviceAccountName,
                                                    String displayName) throws IOException {
    // 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?hl=en#deleting
    String serviceAccountEmail = serviceAccountName + "@" + projectId + ".iam.gserviceaccount.com";

    // 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()) {
      // First, get a service account using getServiceAccount or listServiceAccounts
      GetServiceAccountRequest serviceAccountRequest = GetServiceAccountRequest.newBuilder()
              .setName(ServiceAccountName.of(projectId, serviceAccountEmail).toString())
              .build();
      ServiceAccount serviceAccount = iamClient.getServiceAccount(serviceAccountRequest);

      // You can patch only the `display_name` and `description` fields. You must use
      //  the `update_mask` field to specify which of these fields you want to patch.
      serviceAccount = serviceAccount.toBuilder().setDisplayName(displayName).build();
      PatchServiceAccountRequest patchServiceAccountRequest =
              PatchServiceAccountRequest.newBuilder()
                      .setServiceAccount(serviceAccount)
                      .setUpdateMask(FieldMask.newBuilder().addPaths("display_name").build())
                      .build();
      serviceAccount = iamClient.patchServiceAccount(patchServiceAccountRequest);

      System.out.println(
              "Updated display name for "
                      + serviceAccount.getName()
                      + " to: "
                      + serviceAccount.getDisplayName());
      return serviceAccount;
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Python do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

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


def rename_service_account(
    project_id: str, account: str, new_name: str
) -> types.ServiceAccount:
    """
    Renames service account display name.

    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.
    new_name: New display name of the service account.
    """

    iam_admin_client = iam_admin_v1.IAMClient()

    get_request = types.GetServiceAccountRequest()
    get_request.name = f"projects/{project_id}/serviceAccounts/{account}"
    service_account = iam_admin_client.get_service_account(request=get_request)

    service_account.display_name = new_name

    request = types.PatchServiceAccountRequest()
    request.service_account = service_account
    # You can patch only the `display_name` and `description` fields. You must use
    # the `update_mask` field to specify which of these fields you want to patch.
    # To successfully set update mask you need to transform snake_case field to camelCase.
    # e.g. `display_name` will become `displayName`
    request.update_mask = "displayName"

    updated_account = iam_admin_client.patch_service_account(request=request)
    return updated_account

REST

O método serviceAccounts.patch atualiza 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. Os IDs do projeto são strings alfanuméricas, como my-project.
  • SA_ID: o ID da sua conta de serviço. Pode ser o endereço de e-mail da conta de serviço no formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com ou o ID numérico exclusivo da conta de serviço.
  • SA_NAME: o ID alfanumérico da sua conta de serviço. Esse nome precisa ter entre 6 e 30 caracteres e pode conter caracteres alfanuméricos minúsculos e traços.
  • Substitua pelo menos uma das seguintes opções:
    • UPDATED_DISPLAY_NAME: um novo nome de exibição para sua conta de serviço.
    • UPDATED_DESCRIPTION: uma nova descrição para a conta de serviço.

Método HTTP e URL:

PATCH https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID

Corpo JSON da solicitação:

{
  "serviceAccount": {
    "email": "SA_NAME@PROJECT_ID.iam.gserviceaccount.com",
    "displayName": "UPDATED_DISPLAY_NAME",
    "description": "UPDATED_DESCRIPTION"
  },
  "updateMask": "displayName,description"
}

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",
  "displayName": "My updated service account",
  "description": "An updated description of my service account"
}

A seguir

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