Como gerenciar a representação de uma conta de serviço

Nesta página, descrevemos como permitir que membros e recursos representem uma conta de serviço de gerenciamento de identidade e acesso (IAM, na sigla em inglês). Ela também explica como ver quais membros podem representar uma determinada conta de serviço do IAM.

Antes de começar

Entenda como as contas de serviço funcionam no IAM.

Como permitir que os membros representem contas de serviço

Há vários papéis predefinidos que permitem que um membro represente uma conta de serviço:

  • Usuário da conta de serviço (roles/iam.serviceAccountUser): permite que os membros acessem indiretamente todos os recursos que a conta de serviço pode acessar. Por exemplo, se um membro tiver o papel de usuário da conta de serviço em uma conta de serviço e a conta de serviço tiver o papel de administrador do Cloud SQL (roles/cloudsql.admin) no projeto, o membro poderá representar a conta de serviço para criar um instância do Cloud SQL.

    Esse papel também permite que os membros vinculem uma conta de serviço a um recurso, conforme explicado nesta página.

  • Criador de token de conta de serviço (roles/iam.serviceAccountTokenCreator): os membros podem representar contas de serviço para criar tokens de acesso OAuth 2.0, assinar JSON Web Tokens (JWTs) e assinar blobs binários que podem ser usados para autenticação. Consulte os detalhes em Como criar credenciais da conta de serviço de curta duração.

  • Usuário de identidade de carga de trabalho (roles/iam.workloadIdentityUser): permite que os membros representem contas de serviço das cargas de trabalho do GKE. Esse papel não pode ser concedido em contas de serviço individuais, mas pode ser concedido em um projeto, uma pasta ou uma organização.

Como alternativa, é possível conceder um papel predefinido diferente, ou um papel personalizado, que inclua as mesmas permissões desses papéis.

As seções a seguir descrevem como conceder esses papéis em projetos, pastas e organizações, e como concedê-los em contas de serviço individuais. Escolha o nível com base na quantidade de acesso que você quer conceder:

Como permitir que um membro represente várias contas de serviço

Para permitir que um membro represente todas as contas de serviço criadas em um projeto, pasta ou organização, conceda um papel no projeto, pasta ou organização:

Console

  1. No Console do Cloud, acesse a página IAM.

    Acessar a página do IAM

  2. No seletor de projetos na parte superior da página, escolha o projeto, a pasta ou a organização em que você quer conceder o papel.

  3. Clique em Adicionar.

  4. Digite o endereço de e-mail do membro.

  5. Selecione um papel que permita ao membro representar as contas de serviço. Veja a lista de papéis para representar contas de serviço.

  6. Clique em Salvar.

gcloud

Para conceder a um membro um papel que permita a representação de uma conta de serviço, modifique a política do IAM para seu projeto, pasta ou organização.

  1. Leia a política do IAM para o recurso:

    gcloud resource get-iam-policy resource-id \
        --format=json > policy.json
    

    Substitua os seguintes valores:

    • resource: o tipo de recurso em que você quer definir a política. Esse valor precisa ser um dos seguintes: projects, resource-manager folders ou organizations.
    • resource-id: o ID do recurso em que você quer definir a política.

    O comando armazena a política do recurso em um arquivo policy.json.

    Se uma política já estiver definida no recurso, o arquivo policy.json será semelhante ao seguinte:

    {
      "bindings": [
        {
          "members": [
            "user:hollis@example.com"
          ],
          "role": "roles/owner"
        }
      ],
      "etag": "BwUqLaVeua8=",
      "version": 1
    }
    

    Se não houver política no recurso, o arquivo policy.json conterá apenas o etag padrão.

    Quando não houver política, crie-a manualmente usando o JSON nas etapas a seguir como um modelo.

  2. Modifique a política para conceder os papéis apropriados aos membros. Para conceder um papel, siga um destes procedimentos:

    • Se uma vinculação para o papel não existir, adicione um objeto à matriz bindings que indique o papel que você quer conceder e o membro a quem você quer conceder.
    • Se já houver uma vinculação para o papel, adicione o novo membro à lista de membros atuais. Se a política incluir vinculações de papéis condicionais, verifique também se a vinculação tem as condições apropriadas antes de adicionar o membro.

    Se a matriz bindings ainda não existir, é possível criá-la.

    Exemplo

    Para conceder o papel do usuário da conta de serviço (roles/iam.serviceAccountUser) a robin@example.com, altere o exemplo mostrado na etapa anterior da seguinte maneira:

    {
      "bindings": [
        {
          "role": "roles/iam.serviceAccountUser",
          "members": [
            "user:robin@example.com"
          ]
        },
        {
          "role": "roles/owner",
          "members": [
            "user:hollis@example.com"
          ]
        }
      ],
      "etag": "BwUqLaVeua8=",
      "version": 1
    }
    
  3. Grave a política atualizada:

    gcloud resource set-iam-policy resource-id \
        policy-file
    

    Substitua os seguintes valores:

    • resource: o tipo de recurso em que você quer definir a política. Esse valor precisa ser um dos seguintes: projects, resource-manager folders ou organizations.
    • resource-id: o ID do recurso em que você quer definir a política.
    • policy-file: o caminho para o arquivo que contém a política atualizada.

    O comando imprime a política atualizada com um valor etag atualizado.

REST

Para conceder um papel usando a API REST do Resource Manager, você precisa ler a política atual do IAM para seu projeto, pasta ou organização, modificar a política para conceder os papéis desejados e gravar a política atualizada.

Leia a política do IAM para o recurso.

O método getIamPolicy da API Resource Manager consegue um projeto, uma pasta ou a política do IAM da organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • api-version: a versão da API a ser usada. Para projetos e organizações, use v1. Para pastas, use v2.
  • resource-type: o tipo de recurso com a política que você quer gerenciar. Use o valor projects, folders ou organizations.
  • resource-id: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • 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://cloudresourcemanager.googleapis.com/api-version/resource-type/resource-id:getIamPolicy

Corpo JSON da solicitação:

{
  "options": {
    "requestedPolicyVersion": policy-version
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

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

Quando não houver política, a resposta conterá apenas o padrão etag. Se você receber essa resposta, adicione um campo version, definido como 3 e um campo bindings, definidos como uma matriz vazia.

Modifique a política para conceder os papéis apropriados aos membros.

Para conceder um papel, siga um destes procedimentos:

  • Se uma vinculação para o papel não existir, adicione um objeto à matriz bindings que indique o papel que você quer conceder e o membro a quem você quer conceder.
  • Se já houver uma vinculação para o papel, adicione o novo membro à lista de membros atuais.

Exemplo:

Para conceder o papel do usuário da conta de serviço (roles/iam.serviceAccountUser) a robin@example.com, altere o exemplo mostrado na etapa anterior da seguinte maneira:

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

Grave a política atualizada.

O método setIamPolicy da API Resource Manager define a política na solicitação como a nova política do IAM para o projeto, a pasta ou a organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • api-version: a versão da API a ser usada. Para projetos e organizações, use v1. Para pastas, use v2.
  • resource-type: o tipo de recurso com a política que você quer gerenciar. Use o valor projects, folders ou organizations.
  • resource-id: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • 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/owner",
          "members": [
            "user:owner@example.com"
          ]
        }
      ]
    }
    

Método HTTP e URL:

POST https://iam.googleapis.com/api-version/resource-type/resource-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.

Como permitir que um membro represente uma única conta de serviço

Para permitir que um membro represente uma única conta de serviço, conceda um papel na conta de serviço:

Console

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

    Acessar a página "Contas de Serviço"

  2. Clique em Selecionar um projeto e em Abrir.

  3. Selecione uma conta de serviço Se o painel de informações ainda não estiver visível, clique em Mostrar painel de informações. O painel exibe uma lista de papéis que foram concedidos na conta de serviço.

  4. Clique em Adicionar membro.

  5. Digite o endereço de e-mail do membro.

  6. Selecione um papel que conceda ao membro permissão para representar as contas de serviço. Veja a lista de papéis para representar contas de serviço.

  7. Clique em Adicionar para aplicar o papel ao membro do projeto.

Para conceder papéis em várias contas de serviço, repita essas etapas para cada uma.

gcloud

Para conceder a um membro um papel que permita a representação de uma conta de serviço, modifique a política do IAM da conta de serviço.

  1. Use o comando service-accounts get-iam-policy para ler a política atual:

    gcloud iam service-accounts get-iam-policy sa-id \
        --format=json > policy.json
    

    Substitua os seguintes valores:

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

    O comando armazena a política da conta de serviço em um arquivo policy.json.

    Se uma política já estiver definida na conta de serviço, o arquivo policy.json será semelhante ao seguinte:

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

    Se não houver uma política definida na conta de serviço, o arquivo policy.json conterá apenas o etag padrão.

    Quando não houver política, crie-a manualmente usando o JSON nas etapas a seguir como um modelo.

  2. Em um editor de texto, modifique a matriz de vinculações no arquivo policy.json para conceder os papéis apropriados aos seus membros. Para conceder um papel, siga um destes procedimentos:

    • Se uma vinculação para o papel não existir, adicione um novo objeto à matriz bindings que defina o papel que você quer conceder e o membro a quem você quer conceder.
    • Se já houver uma vinculação para o papel, adicione o novo membro à lista de membros atuais. Se a política incluir vinculações de papéis condicionais, verifique também se a vinculação tem as condições apropriadas antes de adicionar o membro.

    Se a matriz bindings ainda não existir, é possível criá-la.

    Exemplo

    Para conceder o papel do usuário da conta de serviço (roles/iam.serviceAccountUser) a robin@example.com, altere o exemplo mostrado na etapa anterior da seguinte maneira:

    {
      "bindings": [
        {
          "role": "roles/iam.serviceAccountUser",
          "members": [
            "user:robin@example.com"
          ]
        },
        {
          "role": "roles/iam.serviceAccountAdmin",
          "members": [
            "user:hollis@example.com"
          ]
        }
      ],
      "etag": "BwUqLaVeua8=",
      "version": 1
    }
    
  3. Use o comando service-accounts set-iam-policy para gravar a política atualizada:

    gcloud iam service-accounts set-iam-policy sa-id \
        policy-file
    

    Substitua os seguintes valores:

    • 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-file: o caminho para o arquivo que contém a política atualizada.

    O comando imprime a política atualizada com um valor etag atualizado.

REST

Para conceder um papel usando a API REST do IAM, você precisa ler a política atual do IAM da conta de serviço, modificá-la para conceder os papéis desejados e, em seguida, gravar a política atualizada.

Leia a política do IAM da conta de serviç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.
  • 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:

Você receberá uma resposta JSON semelhante a esta:

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

Quando não houver política, a resposta conterá apenas o padrão etag. Se você receber essa resposta, adicione um campo version, definido como 3 e um campo bindings, definidos como uma matriz vazia.

Modifique a política para conceder os papéis apropriados aos membros.

Em um editor de texto, modifique a matriz de vinculações do corpo da resposta para conceder os papéis apropriados aos membros. Para conceder um papel, siga um destes procedimentos:

  • Se uma vinculação para o papel não existir, adicione um novo objeto à matriz bindings que defina o papel que você quer conceder e o membro a quem você quer conceder.
  • Se já houver uma vinculação para o papel, adicione o novo membro à lista de membros atuais.

Exemplo:

Para conceder o papel do usuário da conta de serviço (roles/iam.serviceAccountUser) a robin@example.com, altere o exemplo mostrado na etapa anterior da seguinte maneira:

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

Grave a política atualizada.

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

Como listar membros que podem acessar uma conta de serviço

Use o Console do Cloud para ver todos os membros que têm acesso a uma conta de serviço, seja por papéis concedidos na conta de serviço, seja por papéis concedidos no projeto, na pasta ou na organização:

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

    Acessar a página "Contas de Serviço"

  2. Clique em Selecionar um projeto e em Abrir.

  3. Marque a caixa de seleção ao lado da conta de serviço que você quer.

  4. Se o painel de informações ainda não estiver visível, clique em Mostrar painel de informações. Será exibida uma lista dos papéis que foram concedidos na conta de serviço.

  5. Expanda cada função para visualizar os membros que receberam esse papel na conta de serviço.

Como anexar uma conta de serviço a um recurso

Para alguns recursos do Google Cloud, é possível especificar uma conta de serviço gerenciada pelo usuário que o recurso usa como sua identidade padrão. Esse processo é conhecido como anexar a conta de serviço ao recurso ou a associação da conta de serviço a ele.

Quando o recurso precisa acessar outros serviços e recursos do Google Cloud, ele falsifica a conta de serviço anexada ao recurso. Por exemplo, se você anexar uma conta de serviço a uma instância do Compute Engine, os aplicativos na instância usarão automaticamente essa conta de serviço quando chamarem as APIs do Google Cloud.

Na maioria dos casos, você precisa anexar uma conta de serviço a um recurso ao criá-lo. Após a criação do recurso, não será possível alterar a conta de serviço anexada ao recurso. As instâncias do Compute Engine são uma exceção a essa regra. É possível alterar a conta de serviço anexada a uma instância conforme necessário.

Veja as instruções para o tipo de recurso que você quer criar:

Como anexar uma conta de serviço ao criar um recurso
AI Platform Notebooks Instâncias de notebook
AI Platform Prediction Versões do modelo
AI Platform Training Jobs
Cloud Composer Ambientes
Cloud Functions Função do Cloud
Cloud Life Sciences Pipelines
Cloud Run Serviços
Cloud Scheduler Jobs
Cloud Source Repositories
Compute Engine
Dataflow Jobs
Datalab Instâncias
Dataproc Clusters
Google Kubernetes Engine
Pub/Sub Inscrições

Depois de criar o recurso e anexar a conta de serviço a ele, é possível conceder papéis à conta de serviço para que ela possa acessar os recursos apropriados. Esse processo é o mesmo que conceder um papel a qualquer outro membro.

Para aprender a conceder papéis, consulte Como conceder, alterar e revogar acesso a recursos.

A seguir