Identidade do serviço

Todas as revisões ou jobs do Cloud Run são vinculados a uma conta de serviço. Essa conta de serviço é usada automaticamente pelas bibliotecas de cliente do Google Cloud para fazer a autenticação com as APIs do Google Cloud. Alguns exemplos de APIs do Google Cloud com os quais o código do seu serviço pode interagir: Cloud Storage, Firestore, Cloud SQL, Pub/Sub ou Cloud Tasks.

Se você não especificar uma conta de serviço, o Cloud Run vinculará uma revisão ou um job à conta de serviço padrão que tem permissões amplas em todas as APIs do Google Cloud. O Google recomenda o uso de identidade por serviço e a concessão de permissões seletivas.

Sobre a conta de serviço padrão

Por padrão, as revisões e os jobs do Cloud Run são executados como a conta de serviço padrão do Compute Engine. A conta de serviço padrão do Compute Engine tem o papel do IAM Editor do projeto que concede permissões de leitura e gravação em todos os recursos do projeto do Google Cloud.

Embora isso possa ser conveniente, em vez de usar a conta de serviço padrão, o Google recomenda criar sua própria conta de serviço gerenciada pelo usuário com as permissões mais granulares e atribuí-la como identidade do job ou serviço do Cloud Run. Neste documento, descrevemos como configurar identidades por serviço com o Cloud Run.

Como usar a identidade por serviço

O Google recomenda dar a cada job ou serviço do Cloud Run uma identidade dedicada, atribuindo a ele uma conta de serviço gerenciada pelo usuário em vez de usar a conta de serviço padrão. As contas de serviço gerenciadas pelo usuário permitem que você controle o acesso concedendo um conjunto mínimo de permissões usando o Identity and Access Management.

A CLI do Google Cloud e as bibliotecas de cliente do Google Cloud detectam automaticamente quando estão em execução no Google Cloud e usam o ambiente de execução conta de serviço da revisão atual do Cloud Run. Isso significa que, se o código usar a CLI gcloud ou uma biblioteca de cliente oficial do Google Cloud, ele detectará e autenticará automaticamente como a conta de serviço do ambiente de execução do serviço do Cloud Run. Essa estratégia é chamada de Application Default Credentials e permite a portabilidade de código em vários ambientes.

Há dois aspectos na atribuição da identidade por serviço:

Quais permissões são necessárias para atribuir uma identidade por serviço
Quais permissões a identidade atribuída precisa para funcionar.

Permissões necessárias para atribuir contas de serviço gerenciadas pelo usuário

Para implantar um serviço do Cloud Run usando uma conta de serviço gerenciada pelo usuário, você precisa ter permissão para personificar (iam.serviceAccounts.actAs) essa conta de serviço. Essa permissão pode ser concedida por meio do papel roles/iam.serviceAccountUser do IAM. Todos os principais (por exemplo, usuários, contas de serviço) precisam ter essa permissão na conta de serviço gerenciada pelo usuário para implantar um serviço do Cloud Run como a conta de serviço gerenciada pelo usuário.

Conceda essa permissão usando o console do Google Cloud, por meio da API (YAML) ou usando a gcloud CLI da seguinte maneira:

gcloud iam service-accounts add-iam-policy-binding "SERVICE_ACCOUNT_EMAIL" \
    --member "PRINCIPAL" \
    --role "roles/iam.serviceAccountUser"

Substitua:

SERVICE_ACCOUNT_EMAIL pelo endereço de e-mail da conta de serviço, por exemplo, PROJECT_NUMBER-compute@developer.gserviceaccount.com.
PRINCIPAL pelo principal a que você está adicionando a vinculação. Use o formato user:email, por exemplo, user:test-user@gmail.com.

Para saber como conceder permissões, consulte Como conceder, alterar e revogar acesso a recursos.

Como implantar um novo serviço com uma conta de serviço gerenciada pelo usuário

Se você ainda não tiver uma conta de serviço gerenciada pelo usuário, primeiro crie uma conta de serviço.

É possível definir a conta de serviço do Cloud Run usando o Console do Google Cloud, a CLI gcloud ou a API (YAML) ao criar um novo serviço ou implantar uma nova revisão:

Console

No console do Google Cloud, acesse o Cloud Run:

Acesse o Cloud Run
Clique em Criar serviço se estiver configurando um novo serviço em que fará uma implantação. Se você estiver configurando um serviço atual, clique nele e em Editar e implantar nova revisão.
Se você estiver configurando um novo serviço, preencha a página inicial de configurações do serviço conforme preferir e clique em Contêineres, volumes, rede, segurança para expandir a página de configurações do serviço.
Clique na guia Segurança.
- Clique no menu suspenso Conta de serviço e selecione a conta de serviço desejada.
Clique em Criar ou Implantar.

gcloud

É possível atualizar um serviço existente para ter uma nova conta de serviço de ambiente de execução usando o seguinte comando:

gcloud run services update SERVICE --service-account SERVICE_ACCOUNT

Substitua:

SERVICE pelo nome do serviço;
SERVICE_ACCOUNT pela conta de serviço associada à nova identidade: esse valor é o endereço de e-mail da conta de serviço, por exemplo, example@myproject.iam.gserviceaccount.com.

Também é possível definir uma conta de serviço durante a implantação usando o comando:

gcloud run deploy --image IMAGE_URL --service-account SERVICE_ACCOUNT

Substitua:

IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
SERVICE_ACCOUNT pela conta de serviço associada à nova identidade: esse valor é o endereço de e-mail da conta de serviço, por exemplo, example@myservice.iam.gserviceaccount.com.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

Para visualizar e fazer o download da configuração:

gcloud run services describe SERVICE --format export > service.yaml

Atualize o atributo serviceAccountName::
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      serviceAccountName: SERVICE_ACCOUNT
```
Substitua:
- SERVICE pelo nome do serviço do Cloud Run;
- SERVICE_ACCOUNT pela conta de serviço associada à nova identidade: esse valor é o endereço de e-mail da conta de serviço, por exemplo, example@myproject.iam.gserviceaccount.com.
Substitua o serviço pela nova configuração usando o seguinte comando:
```
gcloud run services replace service.yaml
```

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Para criar uma conta de serviço, adicione o seguinte recurso ao seu arquivo main.tf atual:

resource "google_service_account" "cloudrun_service_identity" {
  account_id = "my-service-account"
}

Crie ou atualize um serviço do Cloud Run e inclua sua conta de serviço:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloud-run-srv"
  location = "us-central1"

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.cloudrun_service_identity.email
  }
}

Como usar contas de serviço em outros projetos

Também é possível usar uma conta de serviço gerenciada pelo usuário que reside em um projeto do Google Cloud diferente do serviço do Cloud Run. Se a conta de serviço e o serviço do Cloud Run estiverem em projetos diferentes:

O projeto que contém essa conta de serviço requer que a política organizacional iam.disableCrossProjectServiceAccountUsage seja definida como falsa/não executada no nível da pasta ou herdada das configurações para envolvidos no projeto. Por padrão, essa opção é definida como true.
A conta de serviço requer uma assinatura de papel de roles/iam.serviceAccountTokenCreator para o agente de serviço do projeto sendo implantado:
```
service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com
```
em que PROJECT_NUMBER é o número do projeto.
A conta de serviço requer uma associação de papel de roles/iam.serviceAccountUser para a identidade (usuário ou automação) que está executando a operação de implantação.

É possível aplicar associações de papéis diretamente ao recurso da conta de serviço ou herdar de níveis mais altos na hierarquia de recursos.

Permissões exigidas por contas de serviço gerenciadas pelo usuário para operar o Cloud Run

Se um serviço do Cloud Run não acessar outras partes do Google Cloud, a conta de serviço não precisará receber nenhum papel ou permissão.

Quando você cria uma nova conta de serviço no Console do Google Cloud, a etapa opcional "Conceder a essa conta de serviço acesso ao projeto" é para qualquer acesso adicional necessário. Por exemplo, um serviço do Cloud Run pode invocar outro serviço particular do Cloud Run ou pode acessar um banco de dados do Cloud SQL, ambos que exigem papéis específicos do IAM. Consulte a documentação sobre como gerenciar o acesso para mais informações.

Como buscar tokens de ID e acesso usando o servidor de metadados

Se o código do serviço do Cloud Run usar uma biblioteca de cliente do Google Cloud, a biblioteca vai adquirir automaticamente os tokens de acesso para autenticar as solicitações do código usando a conta de serviço do ambiente de execução do serviço.

Se você estiver usando seu próprio código personalizado, use o servidor de metadados para buscar tokens de acesso e tokens de ID manualmente. Não é possível consultar esse servidor diretamente de sua máquina local, porque o servidor de metadados só está disponível para cargas de trabalho em execução no Google Cloud.

Os dois tipos de tokens que podem ser buscados com o servidor de metadados são os seguintes:

Tokens de acesso do OAuth 2.0, que são usados para chamar a maioria das APIs do Google.
Tokens de ID, que são usados para chamar outros serviços do Cloud Run ou funções do Cloud Functions, ou para invocar qualquer serviço para validar um token de ID.

Para buscar um token, selecione uma destas opções:

Tokens de acesso

Por exemplo, se você quiser criar um tópico do Pub/Sub, use o método projects.topics.create.

Use o Compute Metadata Server para buscar um token de acesso:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    --header "Metadata-Flavor: Google"

Esse endpoint retorna uma resposta JSON com um atributo access_token.

Na solicitação HTTP/protocolo, ela precisa ser autenticada com um token de acesso no cabeçalho Authorization:
```
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
```
Em que:
- PROJECT_ID é o ID do projeto;
- TOPIC_ID é o ID do tópico.
- ACCESS_TOKEN é o token de acesso que você buscou na etapa anterior.
Resposta:
```
{
    "name": "projects/PROJECT_ID/topics/TOPIC_ID"
}
```

Tokens de ID

Use o Compute Metadata Server para buscar um token de identidade com um público específico:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE" \
    --header "Metadata-Flavor: Google"

Em que AUDIENCE é o público-alvo JWT solicitado.

Para os serviços do Cloud Run, o público-alvo precisa ser o URL do serviço que você está invocando ou um público-alvo personalizado, como um domínio personalizado, configurado para o serviço.

https://service.domain.com

Para outros recursos, é provável que ele seja um ID do cliente OAuth de um recurso protegido pelo IAP:

1234567890.apps.googleusercontent.com

Como receber recomendações para criar contas de serviço dedicadas

O serviço do recomendador fornece recomendações automaticamente para criar contas de serviço dedicadas com o conjunto mínimo de permissões necessárias.

Próximas etapas

Aprenda a gerenciar o acesso ou a autenticar desenvolvedores, serviços e usuários finais aos seus serviços de maneira segura.

Para exibir as instruções completas de um aplicativo que usa a identidade de serviço para minimizar os riscos de segurança, siga o tutorial sobre como proteger os serviços do Cloud Run.