Introdução à identidade de serviço

Nesta página, descrevemos as duas identidades do Cloud Run e como as As bibliotecas de cliente do Cloud usam a identidade do serviço para chamar as APIs do Google Cloud. Exemplos dos produtos do Google Cloud que têm bibliotecas de cliente do Cloud incluem Cloud Storage, Firestore, Cloud SQL, Pub/Sub e, Cloud Tasks. Esta página é destinada a administradores, operadores ou desenvolvedores que gerenciam políticas da organização e acesso de usuários, ou qualquer pessoa que queira saber mais sobre esses tópicos.

Identidades do Cloud Run

Para usar o Cloud Run, o Google Cloud exige que o usuário e a instância do Cloud Run tenham uma identidade.

  • A identidade do usuário do Cloud Run é chamada de conta do implantador do Cloud Run. Ao gerenciar uma revisão ou um job, você usa essa identidade para fazer solicitações à API Cloud Run Admin.
  • A identidade da instância do Cloud Run é chamada de identidade do serviço do Cloud Run. Quando o serviço Cloud Run código que você escreveu interage com as bibliotecas de cliente do Cloud ou chama outra do Google Cloud Run para comunicação de serviço a serviço, você usa essa identidade para fazer solicitações do Cloud Run para APIs do Google Cloud ou outros serviços do Cloud Run.

Para acessar e fazer solicitações às APIs do Google Cloud ou entre serviços, cada identidade precisa ter as permissões concedidas a eles no Identity and Access Management (IAM).

Chamar a API Cloud Run Admin com a conta do implantador

É possível chamar a API Cloud Run Admin do Cloud Run usando a conta do implantador do Cloud Run. A conta do implantador pode ser de usuário ou de serviço e representa a conta que foi conectada ao ambiente do Google Cloud.

Quando a conta do implantador usa o Cloud Run, o IAM verifica se a conta do implantador tem as permissões necessárias para executar a operação do Cloud Run. O diagrama a seguir mostra como uma conta de usuário chama a API Cloud Run Admin para implantar uma nova revisão no console do Google Cloud:

Chame a API Cloud Run Admin no console do Google Cloud.
Figura 1. Um usuário usa o console do Google Cloud para implantar uma nova revisão enviando uma solicitação com um token de acesso para a API Cloud Run Admin. O IAM usa esse token de acesso para verificar se a conta de usuário está autenticada para acessar a API Cloud Run Admin antes de executar a operação.

Chamar as APIs do Google Cloud com a identidade do serviço

Quando uma instância do Cloud Run interage com outras instâncias autenticadas pelo IAM, os serviços do Cloud Run ou chama as bibliotecas de cliente do Cloud com código do aplicativo ou recursos integrados, como Integrações do Cloud Run ou Montagens de volume do Cloud Storage, o ambiente do Google Cloud usa Application Default Credentials (ADC) para detectar automaticamente se a identidade do serviço do Cloud Run está autenticado para executar a operação da API. A identidade de serviço do Cloud Run é uma conta de serviço atribuída como a identidade da instância do Cloud Run quando você implanta uma revisão ou executa um job.

Uma conta de serviço usada como a conta do implantador só será usada como identidade do serviço se você configurar a mesma conta de serviço na configuração do Cloud Run.

O restante deste guia descreve como um serviço ou job do Cloud Run usa a identidade do serviço para chamar e acessar os serviços e as APIs do Google. Para mais informações sobre a configuração de identidade de serviço, consulte as páginas de configuração de identidade de serviço para serviços e jobs.

Tipos de contas de serviço para identidade de serviço

Quando a instância do Cloud Run faz chamadas para as APIs do Google Cloud para executar as operações necessárias, o Cloud Run usa automaticamente uma conta de serviço como a identidade do serviço. Veja a seguir os dois tipos de contas de serviço que podem ser usadas como identidade de serviço:

  • Conta de serviço gerenciada pelo usuário (recomendada): você cria manualmente essa conta de serviço e determina o conjunto mais mínimo de permissões que a conta de serviço precisa para acessar recursos específicos do Google Cloud. A conta de serviço gerenciada pelo usuário segue o formato de SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.
  • Conta de serviço padrão do Compute Engine: o Cloud Run fornece automaticamente a conta de serviço padrão do Compute Engine como a identidade de serviço padrão. A conta de serviço padrão do Compute Engine segue o formato de PROJECT_NUMBER-compute@developer.gserviceaccount.com.

Evitar a conta padrão ao configurar a identidade do serviço

Por padrão, a conta de serviço padrão do Compute Engine é criada automaticamente. Se você não especificar uma conta de serviço quando o serviço ou job do Cloud Run for criado, o Cloud Run vai usar essa conta de serviço.

Dependendo da configuração da política da organização, a conta de serviço padrão pode receber automaticamente o papel de Editor no projeto. É altamente recomendável desativar a concessão automática de papéis aplicando a restrição da política da organização iam.automaticIamGrantsForDefaultServiceAccounts. Se você criou a organização após 3 de maio de 2024, essa restrição será aplicada por padrão.

Se você desativar a concessão automática de papéis, precisará decidir quais papéis conceder às contas de serviço padrão e, em seguida, conceder esses papéis por conta própria.

Se a conta de serviço padrão já tiver o papel de Editor, recomendamos que você o substitua por papéis menos permissivos. Para modificar com segurança os papéis da conta de serviço, use o Simulador de política para ver o impacto da alteração e, em seguida, conceda e revogue os papéis apropriados.

Como a identidade do serviço funciona

Quando o código chama ou faz solicitações para as bibliotecas de cliente do Cloud, acontece o seguinte:

  1. As bibliotecas de cliente detectam que uma solicitação foi feita para uma API do Google Cloud ou para as bibliotecas de cliente do Cloud e solicita um token de acesso do OAuth 2.0 para a identidade do serviço do servidor de metadados da instância.
  2. O servidor de metadados da instância fornece um token de acesso do IAM para a conta de serviço configurada como a identidade do serviço.
  3. A solicitação para a API Google Cloud é enviada com um token de acesso OAuth 2.0.
  4. O IAM verifica a identidade do serviço referenciada no token de acesso para as permissões necessárias e verifica as vinculações de política antes de encaminhar a chamada para o endpoint da API.
  5. A API Google Cloud executa a operação.
Chamar a API Google Cloud pelo Cloud Run.
Figure 2. O Cloud Run gera um token de acesso do servidor de metadados, e o IAM usa esse token de acesso para verificar se a identidade do serviço do Cloud Run atribuída está autenticada para acessar as APIs do Google Cloud.

Gerar um token de acesso para a solicitação do Cloud Run e chamar as APIs do Google Cloud

Se o código do Cloud Run usar bibliotecas de cliente do Cloud, configure a identidade do serviço no Cloud Run atribuindo uma conta de serviço na implantação ou execução. Isso permite que a biblioteca adquira automaticamente um token de acesso para autenticar a solicitação do seu código. Se o código do Cloud Run se comunicar com outros serviços autenticados do Cloud Run, precisa adicionar o token de acesso à sua solicitações.

Para atribuir uma conta de serviço como a identidade do serviço, consulte os seguintes guias:

No entanto, se você usar seu próprio código personalizado ou precisar fazer solicitações de maneira programática, poderá usar o servidor de metadados diretamente para buscar manualmente os tokens de identidade e de acesso descritos nas próxima seção. 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.

Buscar tokens de ID e acesso usando o servidor de metadados

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

Para buscar um token, siga as instruções na guia apropriada para o tipo de token que você está usando:

Tokens de acesso

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

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

  2. Na solicitação de protocolo HTTP, 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

Próximas etapas