Usar a representação da conta de serviço

Quando o principal que você está usando não tem as permissões necessárias para realizar sua tarefa ou você quer usar uma conta de serviço em um ambiente de desenvolvimento, use a representação da conta de serviço.

Ao usar a representação de uma conta de serviço, você começa com um principal autenticado (sua Conta do Google ou uma conta de serviço) e solicita credenciais de curta duração para uma conta de serviço que tenha a autorização exigida pelo seu caso de uso. O principal autenticado precisa ter as permissões necessárias para representar a conta de serviço.

A representação de conta de serviço é mais segura do que usar uma chave de conta de serviço porque a representação requer uma identidade autenticada anterior, e as credenciais criadas usando a representação não permanecem. Em comparação, a autenticação com uma chave de conta de serviço não requer autenticação anterior, e a chave persistente é uma credencial de alto risco, se exposta.

Para mais informações sobre representação da conta de serviço, consulte Representação da conta de serviço.

Antes de começar

Antes de usar a identidade temporária de conta de serviço, ative as APIs necessárias e verifique se você tem os papéis necessários.

Ativar APIs

Para representar uma conta de serviço, é necessário ativar a API Service Account Credentials no seu projeto.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Funções exigidas

Para receber a permissão necessária para representar uma conta de serviço, peça ao administrador para conceder a você o papel do IAM de criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator) 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.getAccessToken que é necessária para representar uma conta de serviço.

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

Você precisa conceder esses papéis à sua conta, mesmo quando estiver trabalhando em um projeto criado.

Para mais informações sobre os papéis necessários para a representação, consulte Papéis para autenticação da conta de serviço.

Use a representação de conta de serviço com os seguintes métodos:

Usar a CLI gcloud

A CLI da gcloud fornece uma maneira simples de usar a representação da conta de serviço. Esse método funciona bem quando você precisa usar uma conta de serviço para acessar recursos ou serviços do Google Cloud usando a CLI gcloud.

É possível personificar uma conta de serviço para um comando específico da CLI da gcloud ou configurar a CLI da gcloud para usar a representação em cada comando automaticamente.

Usar a representação para um comando específico da CLI da gcloud

Para usar a representação em um comando específico da CLI da gcloud, use a sinalização --impersonate-service-account. Por exemplo, o comando a seguir lista os buckets de armazenamento usando a identidade e o acesso fornecidos pela conta de serviço especificada:

gcloud storage buckets list --impersonate-service-account=SERVICE_ACCT_EMAIL

Quando você usa essa sinalização, a CLI da gcloud solicita credenciais de curta duração para a conta de serviço especificada e as usa para autenticar a API e autorizar o acesso. O principal que está conectado à CLI da gcloud (geralmente sua conta de usuário) precisa ter a permissão necessária na conta de serviço.

Usar a representação com a CLI gcloud por padrão

Para configurar a CLI da gcloud para usar a identidade e o acesso fornecidos por uma conta de serviço por padrão, use o comando de configuração da CLI da gcloud:

gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

Com essa propriedade de configuração definida, a CLI da gcloud solicita credenciais de curta duração para a conta de serviço especificada e as usa para autenticar a API e autorizar o acesso ao recurso para cada comando. O principal que está conectado à CLI da gcloud precisa ter a permissão necessária na conta de serviço.

Configurar o Application Default Credentials para usar bibliotecas de cliente

É possível usar a representação de conta de serviço para configurar um arquivo local Application Default Credentials (ADC). As bibliotecas de cliente compatíveis com a representação podem usar essas credenciais automaticamente. Os arquivos ADC locais criados com a representação são compatíveis com os seguintes idiomas:

  • C#
  • Go
  • Java
  • Node.js
  • Python

Use a representação de conta de serviço para criar um arquivo ADC local: 

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Agora é possível usar bibliotecas de cliente com as linguagens compatíveis da mesma forma que você faria depois de configurar um arquivo local do ADC com credenciais de usuário. As credenciais são encontradas automaticamente pelas bibliotecas de autenticação. Para mais informações, consulte Autenticar para usar bibliotecas de cliente.

As credenciais de um arquivo ADC local gerado com a representação de conta de serviço não são compatíveis com todas as bibliotecas de autenticação. Para mais informações, consulte Erro retornado para credenciais locais da representação de conta de serviço.

Gerar e gerenciar credenciais de curta duração

Se nenhum dos métodos anteriores resolver seu caso de uso, será necessário gerar e gerenciar tokens de curta duração. Por exemplo, se você precisar de um tipo diferente de credencial de curta duração (que não seja um token de acesso) ou se precisar usar a representação em um ambiente de produção, use esse método.

Para informações sobre como gerar tokens de curta duração, consulte Criar credenciais de curta duração para uma conta de serviço.

A seguir