Gerenciar o acesso a 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:

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

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 de administrador da conta de serviço (roles/iam.serviceAccountAdmin) na conta de serviço ou no projeto da conta de serviço. Para mais informações sobre como conceder papéis, consulte Gerenciar o acesso.

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

Permissões necessárias

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

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

Ver acesso atual

A seção a seguir mostra como usar o console, 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

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

    Acesse "Contas de serviço"

  2. Selecione um projeto.

  3. Clique no endereço de e-mail da conta de serviço.

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

  5. Opcional: para visualizar concessões de papel para contas de serviço gerenciadas pelo Google, 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 formulário
  • 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.

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

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.

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.

  • 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:

A resposta contém a política de permissão da conta de serviço. 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 e a CLI gcloud 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.

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

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

    Acesse "Contas de serviço"

  2. Selecione um projeto.

  3. Clique no endereço de e-mail da conta de serviço.

  4. Acesse a guia Permissões e encontre a seção Principais com acesso a esta conta de serviço.

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

      Se você quiser conceder um papel a uma conta de serviço gerenciada pelo Google, marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google para ver o e-mail dela.

    • Para conceder a um principal que ainda não tenha outros papéis na conta de serviço, clique em Permitir acesso e insira o endereço de e-mail do principal ou outro identificador.

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

  7. Opcional: adicione uma condição ao papel.

  8. Clique em Save. 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_ID \
    --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.

  • 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_ID: o nome do papel que você quer conceder. Por exemplo, roles/iam.serviceAccountUser. Para ver uma lista de papéis, 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

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

    Acesse "Contas de serviço"

  2. Selecione um projeto.

  3. Clique no endereço de e-mail da conta de serviço.

  4. Acesse a guia Permissões e encontre a seção Principais com acesso a esta conta de serviço.

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

  6. Clique no botão Excluir de cada papel a ser revogado e, em seguida, 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_ID

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.

  • 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_ID: o nome do papel que você quer revogar. Por exemplo, roles/iam.serviceAccountUser. Para uma lista de papéis, 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

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

  1. Leia a política de permissão atual chamando getIamPolicy().
  2. 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;
  3. 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.

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 formulário
  • FORMAT: o formato desejado para a política de permissão. 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 de permissão 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.

  • 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:

A resposta contém a política de permissão da conta de serviço. 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).

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.

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.

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

Para conceder um papel que ainda não está incluído na política de permissão, 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

Edite a política retornada adicionando uma nova vinculação de papel que conceda o papel ao principal.s 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"
  ]
}

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.

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.

Definir a política de permissão

Depois de modificar a política de permissão para conceder e revogar os papéis desejados, 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.

  • PATH: o caminho para um arquivo que contém a nova política de permissão.

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.

  • 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:

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

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