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 gerenciamento de identidade e acesso, o acesso é gerenciado usando as políticas de IAM. Uma política de IAM é 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 IAM, consulte Noções básicas sobre políticas.

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:

Nesta página, descrevemos como gerenciar o acesso a contas de serviço usando o Console do Google Cloud, a ferramenta de linha de comando gcloud e a API REST. Também é possível gerenciar o acesso usando as bibliotecas de cliente do IAM.

Antes de começar

Permissões necessárias

Para gerenciar o acesso a uma conta de serviço, você precisa de um papel que inclua as seguintes permissões:

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

Para ter essas permissões seguindo o princípio do privilégio mínimo, peça ao administrador para conceder a você um dos seguintes papéis:

  • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
  • Administrador de segurança (roles/iam.securityAdmin)

Como alternativa, o administrador pode conceder a você um papel diferente que inclua as permissões necessárias, como um papel personalizado ou um papel predefinido mais permissivo.

Ver acesso atual

A seção a seguir mostra como usar o Console do Cloud, a ferramenta 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 do IAM da conta de serviço.

Console

  1. No Console do Cloud, 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 do IAM da conta de serviço. Para saber como interpretar políticas do IAM, consulte Noções básicas sobre políticas.

Para receber a política do IAM 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 do IAM da conta de serviço. Para saber como interpretar políticas do IAM, consulte Noções básicas sobre políticas.

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 do IAM 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 do Cloud e a ferramenta gcloud para conceder ou revogar rapidamente um único papel a um único principal, sem editar a política do IAM 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.

Conceder um único papel

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

Console

  1. No Console do Cloud, 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á tem outros papéis na conta de serviço, encontre a linha que contém o endereço de e-mail do principal e clique em Editar principal. Em seguida, 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 acesso a um principal que ainda não tem outros papéis na conta de serviço, clique em Conceder acesso e insira o endereço de e-mail do principal.

  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 do Cloud, 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 IAM da conta de serviço:

  1. leitura da política 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. gravação da política atualizada chamando setIamPolicy().

Nesta seção, você verá como usar a ferramenta gcloud e a API REST para atualizar a política. Também é possível atualizar a política usando as bibliotecas de cliente do IAM.

Conseguir a política atual

gcloud

Para receber a política do IAM 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

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 do IAM 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

Modifique a cópia local da política da conta de serviço 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. O campo etag identifica o estado atual da política. Quando você define a política 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. 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.

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ítica retornada adicionando o principal a uma vinculação de papel existente. Essa alteração de política só entrará em vigor quando você definir a política atualizada.

Por exemplo, imagine que a política retornada 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ítica retornada adicionando o principal a uma vinculação de papel existente. Essa alteração de política só entrará em vigor quando você definir a política atualizada.

Por exemplo, imagine que a política retornada 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, 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 de política só entrará em vigor quando você definir a política 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:

{
  "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. Essa alteração de política só entrará em vigor quando você definir a política 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:

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

gcloud

Edite a política retornada removendo o principal ou toda a vinculação de papel. Essa alteração de política só entrará em vigor quando você definir a política atualizada.

Por exemplo, imagine que a política retornada 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.

REST

Edite a política retornada removendo o principal ou toda a vinculação de papel. Essa alteração de política só entrará em vigor quando você definir a política atualizada.

Por exemplo, imagine que a política retornada 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.

Definir a política

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

gcloud

Para definir a política do IAM 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.

A resposta contém a política atualizada.

Por exemplo, o comando a seguir define a política armazenada em policy.json como a política 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 atualizada do IAM 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 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 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