Gerenciar o acesso às contas de serviço

Nesta página, descrevemos como conceder, alterar e revogar o acesso de um principal a uma única conta de serviço. Para gerenciar o acesso de um principal a todas as contas de serviço em um projeto, uma pasta ou uma organização, gerencie o acesso no projeto, na pasta ou na organização.

No Identity and Access Management (IAM), o acesso é gerenciado por meio de políticas de permissão, também conhecidas como políticas do IAM. Uma política de permissão é anexada a um recurso do Google Cloud. Cada política contém uma coleção de vinculações de papéis que associam um ou mais principais, como usuários ou contas de serviço, a um papel do IAM. Essas vinculações de papéis concedem os papéis especificados aos principais no recurso ao qual a política está anexada e em todos os descendentes desse recurso. Para mais informações sobre políticas de permissão, consulte Noções básicas sobre políticas de permissão.

As contas de serviço são recursos aos quais outros principais podem receber acesso e que podem receber acesso a outros recursos. Essa página trata as contas de serviço como recursos e descreve como conceder a outros principais acesso a elas. Para saber como conceder a uma conta de serviço acesso a outros recursos, consulte as seguintes guias:

Para conceder acesso a um projeto, uma pasta ou uma organização a uma conta de serviço, consulte Como gerenciar o acesso a projetos, pastas e organizações.
Para conceder acesso a outros recursos a uma conta de serviço, consulte Como gerenciar o acesso a outros recursos.

Esta página descreve como gerenciar o acesso a contas de serviço usando o Console do Google Cloud, a Google Cloud CLI e a API REST. Também é possível gerenciar o acesso usando as bibliotecas de cliente do IAM.

Antes de começar

Enable the IAM API.
Enable the API
Saiba mais sobre contas de serviço.

Funções exigidas

Para conseguir as permissões necessárias para gerenciar o acesso a uma conta de serviço, peça ao administrador que conceda a você o papel do IAM Administrador da conta de serviço (roles/iam.serviceAccountAdmin) na conta de serviço ou no projeto que detém a conta de serviço. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Este papel predefinido contém as permissões necessárias para gerenciar o acesso a uma conta de serviço. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para gerenciar o acesso a uma conta de serviço:

iam.serviceAccounts.get
iam.serviceAccounts.list
iam.serviceAccounts.getIamPolicy
iam.serviceAccounts.setIamPolicy

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

Ver acesso atual

A seção a seguir mostra como usar o Console do Google Cloud, a CLI gcloud e a API REST para ver quem tem acesso a uma conta de serviço. Também é possível visualizar o acesso usando as bibliotecas de cliente do IAM para receber a política de permissão da conta de serviço.

Console

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

Acesse "Contas de serviço"
Selecione um projeto.
Clique no endereço de e-mail da conta de serviço.
Acesse a guia Permissões. A seção Principais com acesso a esta conta de serviço lista todos os membros que receberam um papel na conta de serviço.

Essa lista inclui principais que têm acesso de papéis concedidos em recursos pai. Para mais informações sobre a herança de políticas, consulte Herança de política e hierarquia de recursos.
Opcional: para visualizar as concessões de papel para agentes de serviço, marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.

gcloud

Para ver quem tem acesso à sua conta de serviço, receba a política de permissão da conta de serviço. Para saber como interpretar políticas de permissão, consulte Noções básicas sobre políticas de permissão.

Para receber a política de permissão para a conta de serviço, execute o comando get-iam-policy para a conta de serviço:

gcloud iam service-accounts get-iam-policy SA_ID --format=FORMAT > PATH

Forneça os valores a seguir:

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.

Observação: se você quiser identificar uma conta de serviço logo depois de criá-la, use o ID numérico em vez do endereço de e-mail para garantir que ela seja identificada de maneira confiável.
FORMAT: o formato da política. Use json ou yaml.
PATH: o caminho para um novo arquivo de saída para a política.

Por exemplo, o comando a seguir recebe a política da conta de serviço my-service-account e a salva no seu diretório inicial no formato JSON:

gcloud iam service-accounts get-iam-policy my-service-account --format json > ~/policy.json

REST

O método serviceAccounts.getIamPolicy recebe a política do IAM 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. 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.

Observação: para identificar uma conta de serviço logo após a criação, use o ID numérico dela, em vez do endereço de e-mail.
POLICY_VERSION: a versão da política a ser retornada. As solicitações precisam especificar a versão mais recente da política, que é a versão 3 da política. Para saber mais detalhes, consulte Como especificar uma versão da política ao receber uma política.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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_ID:getIamPolicy"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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_ID:getIamPolicy" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a política de permissão da conta de serviço. Por exemplo:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

Conceder ou revogar um único papel

É possível usar o Console do Google Cloud e a gcloud CLI para conceder ou revogar rapidamente um único papel a um único principal, sem editar a política de permissão da conta de serviço diretamente. Os tipos comuns de principais incluem contas do Google, contas de serviço, grupos do Google e domínios. Para ver a lista de tipos de principais, consulte Conceitos relacionados à identidade.

Em geral, as alterações na política entram em vigor em até dois minutos. No entanto, em alguns casos, pode levar sete minutos ou mais para que as mudanças sejam propagadas pelo sistema.

Se você precisar de ajuda para identificar o papel predefinido mais apropriado, consulte Escolher papéis predefinidos.

Conceder um único papel

Para conceder um único papel a um principal, faça o seguinte:

Console

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

Acesse "Contas de serviço"
Selecione um projeto.
Clique no endereço de e-mail da conta de serviço.
Acesse a guia Permissões e encontre a seção Principais com acesso a esta conta de serviço.
Selecione um principal para conceder um papel:
- Para conceder um papel a um principal que já tenha outros papéis na conta de serviço, encontre uma linha contendo o principal e clique em Editar principal nessa linha e clique em Adicionar outro papel.
  
  Para conceder um papel a um agente de serviço, marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google para ver o endereço de e-mail dele.
  
  Observação: não é possível editar papéis herdados ao gerenciar o acesso a contas de serviço. Para editar os papéis herdados, acesse o recurso em que o papel foi concedido.
- Para conceder um papel a um principal que ainda não tem papéis na conta de serviço, clique em Conceder acesso e insira o endereço de e-mail do principal ou outro identificador.
Na lista suspensa, selecione um papel a ser concedido. Como prática recomendada de segurança, escolha um papel que inclua apenas as permissões necessárias ao principal.
Opcional: adicione uma condição ao papel.
Clique em Salvar. O principal recebe o papel na conta de serviço.

gcloud

Para conceder um papel a um principal de maneira rápida, execute o comando add-iam-policy-binding:

gcloud iam service-accounts add-iam-policy-binding SA_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Forneça os valores a seguir:

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.

Observação: se você quiser identificar uma conta de serviço logo depois de criá-la, use o ID numérico em vez do endereço de e-mail para garantir que ela seja identificada de maneira confiável.
PRINCIPAL: um identificador para o principal ou membro, que geralmente tem o seguinte formato: PRINCIPAL-TYPE:ID. Por exemplo, user:my-user@example.com. Para ver uma lista completa dos valores que PRINCIPAL pode ter, consulte a referência de vinculação de políticas.

Para o tipo de principal user, o nome de domínio no identificador precisa ser do Google Workspace ou do Cloud Identity. Para saber como configurar um domínio do Cloud Identity, consulte a Visão geral do Cloud Identity.
ROLE_NAME: o nome do papel que você quer conceder. Use um dos seguintes formatos:
- Papéis predefinidos: roles/SERVICE.IDENTIFIER
- Papéis personalizados para envolvidos no projeto: projects/PROJECT_ID/roles/IDENTIFIER
- Papéis personalizados no nível da organização: organizations/ORG_ID/roles/IDENTIFIER
Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.
CONDITION: opcional. A condição a ser adicionada à vinculação de papel. Para mais informações sobre as condições, consulte a Visão geral das condições.

Por exemplo, para conceder o papel de usuário da conta de serviço ao usuário my-user@example.com para a conta de serviço my-service-account@my-project.iam.gserviceaccount.com:

gcloud iam service-accounts add-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
    --member=user:my-user@example.com --role=roles/iam.serviceAccountUser

Revogar um único papel

Para revogar um único papel de um principal, faça o seguinte:

Console

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

Acesse "Contas de serviço"
Selecione um projeto.
Clique no endereço de e-mail da conta de serviço.
Acesse a guia Permissões e encontre a seção Principais com acesso a esta conta de serviço.
Encontre a linha com o endereço de e-mail do principal que tem o acesso que você quer revogar. Em seguida, clique em Editar principal nessa linha.

Observação: não é possível editar papéis herdados ao gerenciar o acesso a contas de serviço. Para editar os papéis herdados, acesse o recurso em que o papel foi concedido.
Clique no botão Excluir do papel que você quer revogar e clique em Salvar.

gcloud

Para revogar um papel de um usuário de maneira rápida, execute o comando remove-iam-policy-binding:

gcloud iam service-accounts remove-iam-policy-binding SA_ID \
    --member=PRINCIPAL --role=ROLE_NAME

Forneça os valores a seguir:

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.

Observação: se você quiser identificar uma conta de serviço logo depois de criá-la, use o ID numérico em vez do endereço de e-mail para garantir que ela seja identificada de maneira confiável.
PRINCIPAL: um identificador para o principal ou membro, que geralmente tem o seguinte formato: PRINCIPAL-TYPE:ID. Por exemplo, user:my-user@example.com. Para ver uma lista completa dos valores que PRINCIPAL pode ter, consulte a referência de vinculação de políticas.

Para o tipo de principal user, o nome de domínio no identificador precisa ser do Google Workspace ou do Cloud Identity. Para saber como configurar um domínio do Cloud Identity, consulte a Visão geral do Cloud Identity.
ROLE_NAME: o nome do papel que você quer revogar. Use um dos seguintes formatos:
- Papéis predefinidos: roles/SERVICE.IDENTIFIER
- Papéis personalizados para envolvidos no projeto: projects/PROJECT_ID/roles/IDENTIFIER
- Papéis personalizados no nível da organização: organizations/ORG_ID/roles/IDENTIFIER
Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.

Por exemplo, para revogar o papel de usuário da conta de serviço do usuário my-user@example.com da conta de serviço my-service-account@my-project.iam.gserviceaccount.com:

gcloud iam service-accounts remove-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
    --member=user:my-user@example.com --role=roles/iam.serviceAccountUser

Conceder ou revogar vários papéis usando o console do Google Cloud

É possível usar o console do Google Cloud para conceder e revogar vários papéis para um único principal:

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

Acessar Contas de serviço
Selecione um projeto.
Clique no endereço de e-mail da conta de serviço.
Acesse a guia Permissões e encontre a seção Principais com acesso a esta conta de serviço.
Selecione o principal com os papéis que você quer modificar:
- Para modificar papéis para um principal que já tem papéis na conta de serviço, encontre a linha que contém o principal e clique em Editar principal nessa linha, e clique em Adicionar outro papel.
  
  Para modificar os papéis de um agente de serviço, selecione a caixa de seleção Incluir concessões de papel fornecidas pelo Google para ver o endereço de e-mail dele.
  
  Observação: não é possível editar papéis herdados ao gerenciar o acesso a contas de serviço. Para editar os papéis herdados, acesse o recurso em que o papel foi concedido.
- Para conceder papéis a um principal que ainda não tem papéis na conta de serviço, clique em Conceder acesso e insira o endereço de e-mail do principal ou outro identificador.
Modifique os papéis do principal:
- Para conceder um papel a um principal que ainda não tem papéis no recurso, clique em Selecionar um papel e selecione um papel na lista suspensa.
- Para conceder outro papel ao principal, clique em Adicionar outro papel e selecione um papel na lista suspensa.
- Para substituir um dos papéis do principal por um diferente, clique nesse papel e escolha outro na lista suspensa.
- Para revogar um dos papéis do principal, clique no botão Excluir de cada papel que você quer revogar.
Também é possível adicionar uma condição a um papel, modificar a condição de um papel ou remover a condição de um papel.
Clique em Salvar.

Conceder ou revogar vários papéis de forma programática

Para fazer alterações de acesso em grande escala que envolvem a concessão e revogação de vários papéis para vários principais, use o padrão read-modify-write para atualizar a política de permissão da conta de serviço:

Leia a política de permissão atual chamando getIamPolicy().
edição da política retornada usando um editor de texto ou de forma programática, para adicionar ou remover qualquer principal ou vinculação de papel;
Escreva a política de permissão atualizada chamando setIamPolicy().

Veja nesta seção como usar a CLI gcloud e a API REST para atualizar a política de permissão. Também é possível atualizar a política usando as bibliotecas de cliente do IAM.

Em geral, as alterações na política entram em vigor em até dois minutos. No entanto, em alguns casos, pode levar sete minutos ou mais para que as mudanças sejam propagadas pelo sistema.

Acessar a política de permissão atual

gcloud

Para receber a política de permissão para a conta de serviço, execute o comando get-iam-policy para a conta de serviço:

gcloud iam service-accounts get-iam-policy SA_ID --format=FORMAT > PATH

Forneça os valores a seguir:

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.

Observação: se você quiser identificar uma conta de serviço logo depois de criá-la, use o ID numérico em vez do endereço de e-mail para garantir que ela seja identificada de maneira confiável.
FORMAT: o formato desejado para a política. Use json ou yaml.
PATH: o caminho para um novo arquivo de saída para a política de permissão.

Por exemplo, o comando a seguir recebe a política de permissão da conta de serviço my-service-account e a salva no seu diretório inicial no formato JSON:

gcloud iam service-accounts get-iam-policy my-service-account --format json > ~/policy.json

REST

O método serviceAccounts.getIamPolicy recebe a política do IAM 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. 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.

Observação: para identificar uma conta de serviço logo após a criação, use o ID numérico dela, em vez do endereço de e-mail.
POLICY_VERSION: a versão da política a ser retornada. As solicitações precisam especificar a versão mais recente da política, que é a versão 3 da política. Para saber mais detalhes, consulte Como especificar uma versão da política ao receber uma política.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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_ID:getIamPolicy"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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_ID:getIamPolicy" | Select-Object -Expand Content

APIs Explorer (navegador)

A resposta contém a política de permissão da conta de serviço. Por exemplo:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

Salve a resposta em um arquivo do tipo apropriado (json ou yaml).

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 Configurar a autenticação para um ambiente de desenvolvimento local.


import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.ServiceAccountName;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.Policy;
import java.io.IOException;

public class GetServiceAccountPolicy {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // TODO: Replace with your project ID.
    String projectId = "your-project-id";
    // TODO: Replace with your service account name.
    String serviceAccount = "your-service-account";
    getPolicy(projectId, serviceAccount);
  }

  // Gets a service account's IAM policy.
  public static Policy getPolicy(String projectId, String serviceAccount) throws IOException {

    // Construct the service account email.
    // You can modify the ".iam.gserviceaccount.com" to match the name of the service account
    // whose allow policy you want to get.
    String serviceAccountEmail = serviceAccount + "@" + 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()) {
      GetIamPolicyRequest request = GetIamPolicyRequest.newBuilder()
              .setResource(ServiceAccountName.of(projectId, serviceAccountEmail).toString())
              .build();
      Policy policy = iamClient.getIamPolicy(request);
      System.out.println("Policy retrieved: " + policy.toString());
      return policy;
    }
  }
}

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 Configurar a autenticação para um ambiente de desenvolvimento local.

from google.cloud import iam_admin_v1
from google.iam.v1 import iam_policy_pb2, policy_pb2


def get_service_account_iam_policy(project_id: str, account: str) -> policy_pb2.Policy:
    """
    Get policy for 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_client = iam_admin_v1.IAMClient()
    request = iam_policy_pb2.GetIamPolicyRequest()
    request.resource = f"projects/{project_id}/serviceAccounts/{account}"

    policy = iam_client.get_iam_policy(request)
    return policy

Modificar a política de permissão

Modifique a cópia local da política de permissão do projeto de maneira programática ou com um editor de texto a fim de refletir os papéis que você quer conceder ou revogar em relação a determinados usuários.

Para garantir que você não substitua outras alterações de política, não edite ou remova o campo etag da política de permissão. O campo etag identifica o estado atual da política de permissão. Quando você define a política de permissão atualizada, o IAM compara o valor etag na solicitação com o etag atual e grava a política somente se os valores corresponderem.

Para editar os papéis que uma política de permissão concede, é necessário editar as vinculações de papéis na política de permissão. As vinculações de papéis têm o seguinte formato:

{
  "role": "ROLE_NAME",
  "members": [
    "PRINCIPAL_1",
    "PRINCIPAL_2",
    ...
    "PRINCIPAL_N"
  ],
  "conditions:" {
    CONDITIONS
  }
}

Os marcadores têm os seguintes valores:

ROLE_NAME: o nome do papel que você quer conceder. Use um dos seguintes formatos:
- Papéis predefinidos: roles/SERVICE.IDENTIFIER
- Papéis personalizados para envolvidos no projeto: projects/PROJECT_ID/roles/IDENTIFIER
- Papéis personalizados no nível da organização: organizations/ORG_ID/roles/IDENTIFIER
Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.
PRINCIPAL_1, PRINCIPAL_2, ...PRINCIPAL_N: identificadores dos principais a que você quer conceder o papel.

Os identificadores dos principais geralmente têm o seguinte formato: PRINCIPAL-TYPE:ID. Por exemplo, user:my-user@example.com. Para ver uma lista completa dos valores que PRINCIPAL pode ter, consulte a referência de vinculação de políticas.

Para o tipo de principal user, o nome de domínio no identificador precisa ser do Google Workspace ou do Cloud Identity. Para saber como configurar um domínio do Cloud Identity, consulte a Visão geral do Cloud Identity.
CONDITIONS: opcional. Todas as condições que especificam quando o acesso será concedido.

Conceder um papel

Para conceder papéis aos principais, modifique as vinculações de papéis na política de permissão. Para saber quais papéis é possível conceder, consulte Noções básicas sobre papéis ou Visualizar papéis atribuíveis para a conta de serviço. Se você precisar de ajuda para identificar os papéis predefinidos mais apropriados, consulte Escolher papéis predefinidos.

Se preferir, use condições para conceder papéis somente quando determinados requisitos forem atendidos.

Para conceder um papel que já está incluído na política, adicione o principal a uma vinculação de papel:

gcloud

Edite a políticade permissão retornada adicionando o principal a uma vinculação de papel existente. Essa mudança só entrará em vigor quando você definir a política de permissão atualizada.

Por exemplo, imagine que a política de permissão contenha a seguinte vinculação de papel, que concede o papel de usuário da conta de serviço (roles/iam.serviceAccountUser) a kai@example.com:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com"
  ]
}

Para conceder esse mesmo papel a raha@example.com, adicione raha@example.com à vinculação de papel existente:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

REST

Edite a políticade permissão retornada adicionando o principal a uma vinculação de papel existente. Essa mudança só entrará em vigor quando você definir a política de permissão atualizada.

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com"
  ]
}

Para conceder esse mesmo papel a raha@example.com, adicione raha@example.com à vinculação de papel existente:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

Para conceder um papel que ainda não está incluído na política, adicione uma nova vinculação de papel:

gcloud

Edite a política retornada adicionando uma nova vinculação de papel que conceda o papel ao principal. Essa alteração não entrará em vigor até que você defina a política de permissão atualizada.

Por exemplo, para conceder o papel de criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) a raha@example.com, adicione a seguinte vinculação de papel à matriz bindings da política de permissão:

{
  "role": "roles/iam.serviceAccountTokenCreator",
  "members": [
    "user:raha@example.com"
  ]
}

REST

{
  "role": "roles/iam.serviceAccountTokenCreator",
  "members": [
    "user:raha@example.com"
  ]
}

Revogar um papel

Para revogar um papel, remova o principal da vinculação de papel. Se não houver outros principais na vinculação de papel, remova toda a vinculação de papel da política de permissão.

gcloud

Edite a políticade permissão removendo o principal ou toda a vinculação de papéis. Essa alteração não entrará em vigor até que você defina a política de permissão atualizada.

Por exemplo, imagine que a política de permissão contenha a seguinte vinculação de papel, que concede a kai@example.com e raha@example.com o papel de usuário da conta de serviço (roles/iam.serviceAccountUser):

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

Para revogar o papel de kai@example.com, remova kai@example.com da vinculação de papel:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:raha@example.com"
  ]
}

Para revogar o papel de kai@example.com e raha@example.com, remova a vinculação de papel da política de permissão.

REST

Edite a políticade permissão removendo o principal ou toda a vinculação de papéis. Essa alteração não entrará em vigor até que você defina a política de permissão atualizada.

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

Para revogar o papel de kai@example.com, remova kai@example.com da vinculação de papel:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:raha@example.com"
  ]
}

Para revogar o papel de kai@example.com e raha@example.com, remova a vinculação de papel da política de permissão.

Definir a política de permissão

Depois de modificar a política de permissão para conceder e revogar papéis, chame setIamPolicy() para fazer as atualizações.

gcloud

Para definir a política de permissão para o recurso, execute o comando set-iam-policy para a conta de serviço:

gcloud iam service-accounts set-iam-policy SA_ID PATH

Forneça os valores a seguir:

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.

Observação: se você quiser identificar uma conta de serviço logo depois de criá-la, use o ID numérico em vez do endereço de e-mail para garantir que ela seja identificada de maneira confiável.
PATH: o caminho para um arquivo que contém a nova política.

A resposta contém a políticade permissão atualizada:

Por exemplo, o comando a seguir define a política de permissão armazenada em policy.json como a política de permissão da conta de serviço my-service-account@my-project.iam.gserviceaccount.com:

gcloud iam service-accounts set-iam-policy my-service-account@my-project.iam.gserviceaccount.com \
    ~/policy.json

REST

O método serviceAccounts.setIamPolicy define uma política de permissão atualizada para a 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.

Observação: para identificar uma conta de serviço logo após a criação, use o ID numérico dela, em vez do endereço de e-mail.

POLICY: uma representação JSON da política que você quer definir. Para mais informações sobre o formato de uma política, consulte a referência da política.

Por exemplo, para definir a política de permissão mostrada na etapa anterior, substitua policy pelo seguinte:

{
  "version": 1,
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
        "user:robin@example.com"
      ]
    },
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "policy": POLICY
}

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

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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_ID:setIamPolicy"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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_ID:setIamPolicy" | Select-Object -Expand Content

APIs Explorer (navegador)

A resposta contém a política de permissão atualizada.

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 Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.ServiceAccountName;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

public class SetServiceAccountPolicy {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // TODO: Replace with your project ID.
    String projectId = "your-project-id";
    // TODO: Replace with your service account name.
    String serviceAccount = "your-service-account";
    // TODO: Replace with your policy, GetPolicy.getPolicy(projectId, serviceAccount).
    Policy policy = Policy.newBuilder().build();

    setServiceAccountPolicy(policy, projectId, serviceAccount);
  }

  // Sets a service account's policy.
  public static Policy setServiceAccountPolicy(Policy policy, String projectId,
                                               String serviceAccount) throws IOException {

    // Construct the service account email.
    // You can modify the ".iam.gserviceaccount.com" to match the name of the service account
    // whose allow policy you want to set.
    String accountEmail = String.format("%s@%s.iam.gserviceaccount.com", serviceAccount, 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()) {
      List<String> paths = Arrays.asList("bindings", "etag");
      SetIamPolicyRequest request = SetIamPolicyRequest.newBuilder()
              .setResource(ServiceAccountName.of(projectId, accountEmail).toString())
              .setPolicy(policy)
              // A FieldMask specifying which fields of the policy to modify. Only
              // the fields in the mask will be modified. If no mask is provided, the
              // following default mask is used:
              // `paths: "bindings, etag"`
              .setUpdateMask(FieldMask.newBuilder().addAllPaths(paths).build())
              .build();

      return iamClient.setIamPolicy(request);
    }
  }
}

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 Configurar a autenticação para um ambiente de desenvolvimento local.

from google.cloud import iam_admin_v1
from google.iam.v1 import iam_policy_pb2, policy_pb2


def set_service_account_iam_policy(
    project_id: str, account: str, policy: policy_pb2.Policy
) -> policy_pb2.Policy:
    """
    Set policy for service account. Pay attention that previous state will be completely rewritten.
    If you want to update only part of the policy follow the approach read->modify->write.
    For more details about policies check out https://cloud.google.com/iam/docs/policies

    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.
    policy: Policy which has to be set.
    """

    # Same approach as for policies on project level, but client stub is different.
    iam_client = iam_admin_v1.IAMClient()
    request = iam_policy_pb2.SetIamPolicyRequest()
    request.resource = f"projects/{project_id}/serviceAccounts/{account}"

    # request.etag field also will be merged which means you are secured from collision,
    # but it means that request may fail and you need to leverage exponential reties approach
    # to be sure policy has been updated.
    request.policy.MergeFrom(policy)

    policy = iam_client.set_iam_policy(request)
    return policy

A seguir

Saiba quais papéis conceder para que os principais façam a autenticação como contas de serviço.
Saiba como escolher os papéis predefinidos mais apropriados.
Consulte as Práticas recomendadas para trabalhar com contas de serviço e saiba como usar as contas de serviço de maneira segura.
Saiba como gerenciar o acesso a projetos, pastas e organizações.
Conheça as etapas gerais para gerenciar o acesso a outros recursos.
Aprenda a tornar o acesso de um principal condicional com as vinculações de papéis condicionais.

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