Anexar contas de serviço a recursos

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 código em execução no recurso acessa serviços e recursos do Google Cloud, ele usa a conta de serviço anexada ao recurso como identidade. Por exemplo, se você anexar uma conta de serviço a uma instância do Compute Engine e os aplicativos na instância usarem uma biblioteca de cliente para chamar as APIs do Google Cloud, esses aplicativos usam automaticamente a conta de serviço anexada para autenticação e autorização.

Veja nesta página como configurar contas de serviço para anexá-las a recursos.

Antes de começar

Funções exigidas

Para receber a permissão necessária para anexar uma conta de serviço a um recurso, peça ao administrador para conceder a você o papel do IAM de Usuário da conta de serviço (roles/iam.serviceAccountUser) na 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.

Esse papel predefinido contém a permissão iam.serviceAccounts.actAs, que é necessária para anexar uma conta de serviço a um recurso.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Anexar uma conta de serviço a um recurso

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.

Antes de anexar uma conta de serviço a um recurso, é preciso configurar a conta de serviço. Esse processo será diferente se a conta de serviço e o recurso estiverem no mesmo projeto ou em projetos diferentes. Depois de configurar a conta de serviço, crie o recurso e anexe a conta de serviço a esse recurso.

Configurar um recurso no mesmo projeto

Antes de anexar uma conta de serviço a outro recurso no mesmo projeto, conceda papéis à conta de serviço para que ela possa acessar os recursos adequados, assim como você faria com papéis a qualquer outro principal.

Configurar um recurso em um projeto diferente

Em alguns casos, pode ser necessário anexar uma conta de serviço a um recurso localizado em outro projeto. Por exemplo, se você criar todas as suas contas de serviço em um único projeto, talvez seja necessário anexar uma delas a um novo recurso em um projeto diferente.

Antes de anexar uma conta de serviço a um recurso em outro projeto, faça o seguinte:

  1. No projeto em que a conta de serviço está localizada, siga as etapas nesta página para ativar a vinculação de contas de serviço em projetos.
  2. Identifique o projeto em que você criará o recurso.

  3. Identifique o tipo de recurso ao qual a conta de serviço será anexada, bem como o serviço que possui esse tipo de recurso.

    Por exemplo, se você estiver criando uma assinatura do Pub/Sub, o Pub/Sub será o serviço proprietário do recurso.

  4. Encontre o endereço de e-mail do agente de serviços.

    Diferentes serviços usam agentes de serviço distintos. Para detalhes, consulte Agentes de serviço.

  5. Conceda o papel Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) aos agentes de serviço:

    Console

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

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

    2. Selecione o projeto proprietário da conta de serviço que você anexará a um recurso.

    3. Clique no endereço de e-mail da conta de serviço que você anexará a um recurso.

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

    5. Clique em Conceder acesso e insira o endereço de e-mail do agente de serviço.

    6. Clique em Selecionar um papel, digite Service Account Token Creator e clique nele.

    7. Clique em Salvar.

    8. Opcional: se você precisar conceder o papel a outro agente de serviço, repita as etapas anteriores.

    gcloud

    Use o comando gcloud iam service-accounts add-iam-policy-binding:

    gcloud iam service-accounts add-iam-policy-binding \
    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --member=serviceAccount:SERVICE_AGENT_EMAIL \
    --role=roles/iam.serviceAccountTokenCreator

    Substitua os seguintes valores:

    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário que você está anexando a um recurso.
    • PROJECT_ID: o ID do projeto em que a conta de serviço gerenciada pelo usuário está localizada.
    • SERVICE_AGENT_EMAIL: o endereço de e-mail da do agente de serviço.

    O comando imprime a política e permissão datualizada na conta de serviço gerenciada pelo usuário.

    Opcional: se você precisar conceder o papel a outro agente de serviço, execute o comando novamente.

    REST

    Para conceder esse papel, use o padrão read-modify-write para atualizar a política de permissão para sua conta de serviço gerenciada pelo usuário.

    Primeiro, leia a política do IAM da conta de serviço gerenciada pelo usuário:

    O método projects.serviceAccounts.getIamPolicy retorna a política de permissão da 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.
    • USER_SA_NAME: o nome da conta de serviço gerenciada pelo usuário que você está vinculando a um recurso.

    Método HTTP e URL:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/USER_SA_NAME@PROJECT_ID.iam.gserviceaccount.com:getIamPolicy

    Corpo JSON da solicitação:

    {
  "requestedPolicyVersion": 3
}

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

    Você receberá uma resposta JSON semelhante a esta:

    {
  "version": 1,
  "etag": "BwWl3KCTUMY=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
        "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com"
      ]
    }
  ]
}

    Em seguida, altere a política para conceder o papel de Criador de token da conta de serviço ao agente de serviço.

    {
  "version": 1,
  "etag": "BwWl3KCTUMY=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:SERVICE_AGENT_EMAIL"
      ]
    },
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
        "serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
      ]
    }
  ]
}

    Substitua:

    • SERVICE_AGENT_EMAIL: o endereço de e-mail do agente de serviço.
    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário.
    • PROJECT_ID: o ID do projeto em que a conta de serviço gerenciada pelo usuário está localizada.

    Por fim, escreva a política de permissão atualizada:

    O método projects.serviceAccounts.setIamPolicy atualiza a política de permissão para sua 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.
    • USER_SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário que você está vinculando a um recurso.
    • SERVICE_AGENT_EMAIL: o endereço de e-mail do agente de serviço que criará tokens de acesso para a conta de serviço gerenciada pelo usuário.

    Método HTTP e URL:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com:setIamPolicy

    Corpo JSON da solicitação:

    {
  "policy": {
    "version": 1,
    "etag": "BwWl3KCTUMY=",
    "bindings": [
      {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
          "serviceAccount:SERVICE_AGENT_EMAIL"
        ]
      },
      {
        "role": "roles/iam.serviceAccountUser",
        "members": [
          "serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
        ]
      }
    ]
  }
}

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

    Você receberá uma resposta JSON semelhante a esta:

    {
  "version": 1,
  "etag": "BwWo331TkHE=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:SERVICE_AGENT_EMAIL"
      ]
    },
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
        "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com"
      ]
    }
  ]
}

Anexar a conta de serviço ao novo recurso

Depois de configurar a conta de serviço gerenciada pelo usuário, é possível criar um novo recurso e anexar a conta a esse recurso. Certifique-se de criar o novo recurso no projeto apropriado.

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 Prediction Versões do modelo
AI Platform Training Jobs
Ambiente padrão do App Engine Versões do app
Ambiente flexível do App Engine Versões do app
Cloud Composer Ambientes
Funções do Cloud Run Função do Cloud Run
Cloud Life Sciences Pipelines
Cloud Run Serviços
Cloud Scheduler Jobs
Cloud Source Repositories
Compute Engine
Dataflow Jobs
Datalab Instâncias
Dataproc Clusters
Eventarc Gatilhos
Google Kubernetes Engine
Notebooks Instâncias de notebook
Pub/Sub Assinaturas
Vertex AI
Fluxos de trabalho Workflows

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

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

Anexar uma conta de serviço a um recurso em outro projeto

Por padrão, não é possível criar uma conta de serviço em um projeto e anexá-la a um recurso em outro projeto. Se você quiser manter todas as suas contas de serviço em um projeto, atualize a política da organização para esse projeto.

Ativar contas de serviço para serem anexadas a projetos

Para permitir que os usuários anexem contas de serviço em um projeto aos recursos de outro, verifique as seguintes restrições booleanas na política da organização do projeto em que suas contas de serviço estão localizadas:

  • Certifique-se de que a restrição booleana iam.disableCrossProjectServiceAccountUsage não seja aplicada ao projeto.

    Essa restrição booleana controla se é possível anexar uma conta de serviço a um recurso em outro projeto. A restrição é aplicada por padrão.

    Quando essa restrição não é aplicada, o IAM adiciona uma garantia de projeto que impede que ele seja excluído. Essa garantia tem a origem iam.googleapis.com/cross-project-service-accounts. Não é recomendável excluir essa garantia.

  • Recomendado: certifique-se de que a restrição booleana iam.restrictCrossProjectServiceAccountLienRemoval seja aplicada ao projeto.

    Essa restrição booleana garante que os principais removam a garantia do projeto somente se tiverem a permissão resourcemanager.projects.updateLiens no nível da organização. Se essa restrição não for aplicada, os principais poderão remover a garantia do projeto se tiverem essa permissão no nível do projeto.

Para saber como visualizar ou alterar uma restrição booleana em uma política da organização, consulte Como criar e gerenciar políticas da organização.

Desativar a anexação de contas de serviço entre projetos

Se você ativou a vinculação de contas de serviço em todos os projetos, não recomendamos desativar esse recurso, especialmente em ambientes de produção.

Especificamente, não faça nenhuma dessas alterações no projeto em que estão localizadas as contas de serviço:

  • Não atualize a política da organização do projeto para aplicar a restrição booleana iam.disableCrossProjectServiceAccountUsage.
  • Não atualize a política da organização do projeto para não aplicar a restrição booleana iam.restrictCrossProjectServiceAccountLienRemoval.
  • Não remova a garantia do projeto com a origem iam.googleapis.com/cross-project-service-accounts, que impede você de excluir o projeto.
  • Não exclua o projeto.

Se você quiser aceitar o risco de desativar esse recurso, desative as contas de serviço usadas em todos os projetos e monitore os problemas do ambiente do Google Cloud. Se você tiver algum problema, reative as contas de serviço. Se você não encontrar problemas, talvez não tenha os recursos do Google Cloud que dependam de uma conta de serviço em um projeto diferente.

Registros de auditoria para vincular contas de serviço

Quando um principal usa a permissão iam.serviceAccounts.actAs para anexar uma conta de serviço a um recurso, o IAM gera um registro de auditoria. Esse registro de auditoria contém as seguintes informações:

  • O endereço de e-mail do principal que anexou a conta de serviço ao recurso
  • Detalhes sobre a conta de serviço anexada ao recurso

Para conferir uma lista de recursos que podem ser anexados a contas de serviço, consulte Anexar a conta de serviço ao novo recurso nesta página.

Para conferir um exemplo desse tipo de registro de auditoria, consulte Registros para usar a permissão iam.serviceAccounts.actAs. Para saber mais sobre registros de auditoria em geral, consulte Visão geral dos Registros de auditoria do Cloud.

A seguir