GCP - Service Account Impersonation

Esta documentação descreve como configurar e utilizar a Service Account (SA) Impersonation no Google Cloud Platform (GCP) para permitir que um usuário ou serviço atue em nome de uma SA específica. A impersonação de SAs é útil para delegar permissões e acessar recursos do GCP de maneira segura e controlada.

Conteúdo

O que é Service Account Impersonation?
Como funciona?
Pré-requisitos
Configuração de Service Account Impersonation
Uso de Service Account Impersonation (desenvolvimento local)
- Via gcloud CLI (Command Line Interface)
- Via Código
Deploy da aplicação no ambiente GCP
Boas Práticas
Referências

O que é Service Account Impersonation?

Antes de entender sobre SA Impersonation, é importante compreender o que é uma Service Account (SA). Uma SA é uma identidade especial usada por aplicativos e serviços para interagir com APIs do Google Cloud. Diferente das contas de usuário, as SAs são gerenciadas pelo sistema e não estão associadas a um usuário específico. A autorização de uma conta de serviço é gerenciada através do IAM (Identity and Access Management). Você concede papéis (roles) a uma conta de serviço, definindo exatamente quais permissões ela tem sobre quais recursos. Por exemplo, você pode dar a uma conta de serviço a permissão para apenas ler objetos de um bucket específico no Cloud Storage. Isso permite aplicar o princípio do menor privilégio, garantindo que a aplicação só acesse o que for estritamente necessário.

A Service Account Impersonation permite que um usuário ou serviço assuma a identidade de uma SA para acessar recursos do GCP. Isso é feito concedendo permissões específicas ao usuário ou serviço para "impersonar" a SA, permitindo que ele execute ações em nome dessa conta.

Quando você usa este método, você começa como um usuário autenticado 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 usuário autenticado precisa ter as permissões necessárias para representar a conta de serviço. Esse processo acaba se tornando mais seguro por três motivos:

Você não precisa distribuir chaves de conta de serviço, que podem ser perdidas ou comprometidas.
Você pode auditar o uso da conta de serviço, pois as ações são registradas como realizadas pelo usuário autenticado.
As credenciais de curta duração são automaticamente revogadas após um período de tempo, reduzindo o risco de uso indevido.

Como funciona?

sequenceDiagram
    participant User
    participant IAM as IAM Service
    participant SA1 as Service Account 1
    participant SA2 as Service Account 2
    participant Resource as GCP Resource
    User->>IAM: Authenticate with user credentials
    IAM->>User: Grant temporary credentials
    User->>IAM: Request to impersonate SA1
    IAM->>IAM: Check if user has permission to impersonate SA1
    IAM->>SA1: Generate short-lived credentials for SA1
    SA1->>User: Provide impersonated credentials
    User->>IAM: Use SA1 credentials to impersonate SA2
    IAM->>IAM: Check if SA1 has permission to impersonate SA2
    IAM->>SA2: Generate short-lived credentials for SA2
    SA2->>User: Provide impersonated credentials
    User->>Resource: Access resource using SA2 credentials
    Resource->>Resource: Verify SA2 permissions
    Resource->>User: Grant or deny access based on SA2 permissions

Uma conta de usuário ou serviço solicita a representação de uma conta de serviço de destino.
O IAM verifica se o solicitante possui as permissões necessárias para representar o destino.
Se autorizado, o GCP gera credenciais de curta duração para a conta de serviço de destino.
O solicitante usa essas credenciais temporárias para acessar recursos.
O recurso valida as credenciais e concede acesso com base nas permissões da conta de serviço de destino.

Pré-requisitos

Para utilizar a Service Account Impersonation, você precisa atender aos seguintes pré-requisitos:

Ativar a API IAM Service Account Credentials no projeto do GCP.
Ter uma conta do Google Cloud com permissões adequadas.
- Conceder permissões de impersonation ao usuário ou serviço que irá assumir a SA. Para isto é necessário atribuir o papel roles/iam.serviceAccountTokenCreator ao usuário ou serviço na SA que será impersonada.
Ter uma Service Account (SA) criada no projeto do GCP.

Configuração de Service Account Impersonation

Para configurar a Service Account Impersonation, siga os passos abaixo:

Acesse o Console do Google Cloud.
Navegue até a seção "IAM & Admin" e selecione "Service Accounts".
Selecione a SA que você deseja que seja impersonada.
Clique na aba "Permissions" e adicione o usuário ou serviço que irá assumir a SA.
Atribua o papel roles/iam.serviceAccountTokenCreator ao usuário ou serviço.
Salve as alterações.

Uso de Service Account Impersonation (desenvolvimento local)

Via gcloud CLI (Command Line Interface)

Uma forma simples de utilizar a Service Account Impersonation é através da CLI da 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 impersonation em cada comando automaticamente.

Em um comando 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="seu-email-da-sa@seu-projeto.iam.gserviceaccount.com"

Caso você queira desenvolver um script ou aplicação que utilize a impersonação de SA sem adicionar linhas em seu código, autentique e configure o Application Default Credentials (ADC). Para isso, no seu terminal local, você vai configurar o ambiente para que as bibliotecas de cliente do Google Cloud usem suas credenciais de usuário para impersonificar a service account.

Faça login com sua conta de usuário:

gcloud auth login

Configure o ADC para usar a impersonação de SA:

gcloud auth application-default login --impersonate-service-account="seu-email-da-sa@seu-projeto.iam.gserviceaccount.com"

Este comando gera um arquivo de credenciais localmente (~/.config/gcloud/application_default_credentials.json) que informa às bibliotecas do Google Cloud para primeiro se autenticarem como seu usuário e, em seguida, obter um token de curta duração para a service account especificada.

Após configurar o ADC, as bibliotecas cliente do Google Cloud usarão automaticamente a conta de serviço impersonificada para autenticação. Você pode verificar se a configuração foi bem-sucedida executando o seguinte comando:

gcloud auth application-default print-access-token

A vantagem dessa abordagem é que o código não precisa de nenhuma alteração especial. As bibliotecas de cliente do Google Cloud (google-cloud-aiplatform, google-cloud-storage, etc.) procuram automaticamente por essas credenciais de ambiente (ADC). Seu código para inicializar os clientes do Vertex AI (para o Gemini) e do Cloud Storage, por exemplo, permanecerá simples, sem nenhuma referência a arquivos de chave.

Via Código

Para utilizar a Service Account Impersonation em seu código, você pode usar a biblioteca cliente do Google Cloud para a linguagem de programação de sua escolha (REST, Go, Java, Node.js, Python). Abaixo está um exemplo em Python utilizando a biblioteca google-auth e google-cloud-storage. Para usar as credenciais da SA, seu aplicativo precisa ser autenticado primeiro com credenciais de origem.

from google.auth import impersonated_credentials
from google.cloud import storage
from google.oauth2 import service_account
from google.auth.transport.requests import Request
import google.auth
import os
 
# Função para listar arquivos em um bucket do GCP usando impersonação de SA
def list_files(bucket_name, target_sa_email):
    # Obter credenciais padrão (pode ser do ambiente ou metadata do GCP)
    source_credentials, project_id = google.auth.default()
    
    # Configurar credenciais de impersonação
    target_scopes = ['https://www.googleapis.com/auth/cloud-platform']
    impersonated_creds = impersonated_credentials.Credentials(
        source_credentials=source_credentials,
        target_principal=target_sa_email,
        target_scopes=target_scopes,
        lifetime=3600
    )
    
    # Criar cliente do Storage com as credenciais de impersonação
    storage_client = storage.Client(credentials=impersonated_creds, project=project_id)
    
    # Listar arquivos no bucket especificado
    bucket = storage_client.bucket(bucket_name)
    blobs = bucket.list_blobs()
    
    print(f"Arquivos no bucket {bucket_name}:")
    for blob in blobs:
        print(blob.name)
    
# Exemplo de uso
if __name__ == "__main__":
    bucket_name = "seu-bucket-aqui"
    target_sa_email = os.getenv("TARGET_SA_EMAIL")  #"seu-email-da-sa@seu-projeto.iam.gserviceaccount.com"
    list_files(bucket_name, target_sa_email)

Deploy da aplicação no ambiente GCP

Quando a aplicação está sendo executada em um ambiente do GCP (como Compute Engine, Cloud Run, App Engine, etc.), o processo de impersonação não se torna necessário, pois para a maioria dos serviços, é possível "anexar" uma service account diretamente à instância ou serviço. Dessa forma, a aplicação pode usar as permissões da service account sem a necessidade de impersonação. Como exemplo, podemos citar o Cloud Run, onde é possível selecionar a service account que o serviço irá utilizar diretamente no comando de deploy:

gcloud run deploy [NOME_DO_SERVICO] \
    --image=$IMAGE_URI \ 
    --platform=managed \
    --region=$LOCATION \
    --allow-unauthenticated \
    --env-vars-file=env.yaml \
    --service-account=$SERVICE_ACCOUNT_EMAIL

Agora, considerando um cenário no qual temos um ambiente de nuvem híbrida/multicloud, a solução recomendada e mais segura para que uma aplicação em outro provedor acesse recursos do Google Cloud (como a API do Gemini no AI Platform/Vertex AI) é usar o Workload Identity Federation (Federação de Identidade de Carga de Trabalho). Essa é uma funcionalidade de segurança do GCP que permite que aplicações executando fora do Google Cloud acessem recursos do GCP sem a necessidade de gerenciar chaves de conta de serviço de longa duração. É possível usar o Workload Identity Federation com workloads que executam em Amazon Web Services (AWS), Azure, Active Directory local, serviços de deployment como GitHub e GitLab, e com qualquer provedor de identidade (IdP) que suporte OpenID Connect (OIDC) ou Security Assertion Markup Language (SAML) V2.0.

Boas Práticas

Sempre utilize o menor escopo de permissões necessário para a Service Account (princípio do menor privilégio).
Revogue as permissões de impersonação quando não forem mais necessárias.
Monitore o uso da Service Account e audite as ações realizadas em seu nome.
Use tokens de curta duração (a expiração padrão de 1 hora geralmente é uma boa opção)
Audite regularmente os relacionamentos de personificação.

Service Account Impersonation - GCP