Públicos-alvo personalizados (serviços)

Esta página descreve como usar públicos-alvo personalizados para autorização.

Os clientes que chamam um serviço do Cloud Run protegido pelo Identity and Access Management precisam fornecer um token de ID válido que inclua uma declaração de público-alvo correspondente ao URL *.run.app do serviço recebido. Para clientes que não conhecem esse URL, é possível usar um valor de público-alvo personalizado.

Entendendo os públicos-alvo personalizados

O Cloud Run fornece um papel de invocador (roles/run.invoker) para dar suporte ao controle de acesso com o IAM. O controle de acesso do IAM usa tokens de código assinados pelo Google, que são empacotados como JSON Web Tokens (JWTs). O conteúdo desses tokens está em conformidade com um padrão OIDC.

Um campo de público-alvo é codificado no token para especificar o destino pretendido que pode usá-lo. Isso limita o risco de um ataque de repetição, em que um token interceptado destinado ao uso com um serviço é reproduzido novamente em um serviço diferente.

Por convenção, o público é o URL completo do serviço de destino. Por padrão, no Cloud Run, esse é o URL gerado pelo Google para um serviço que termina em run.app.

No entanto, um serviço do Cloud Run pode estar atrás de um URL diferente do URL gerado por padrão, como nos cenários a seguir:

Ao usar um domínio personalizado para acessar um serviço em que o cliente não sabe qual é o URL gerado pelo Google.
Ao implantar vários serviços atrás de um balanceador de carga em que um cliente não consegue prever qual serviço regional será acessado por uma solicitação. Os URLs gerados pelo Google para serviços são específicos da região, mesmo que o nome do serviço seja igual.

Nesses cenários, é preciso configurar um serviço para aceitar valores de público-alvo personalizados que permitem outros destinos conhecidos por um cliente. O URL padrão gerado pelo Google permanece sempre como um valor de público-alvo aceito.

Definir e atualizar públicos-alvo personalizados

A definição de públicos-alvo personalizados para o Cloud Run acontece no nível de serviço e se aplica a todas as revisões de disponibilização, semelhante à assinatura de autorização do IAM.

É possível definir vários públicos-alvo personalizados, desde que a codificação JSON deles como lista de strings não exceda 32.768 caracteres.

Qualquer mudança na configuração leva à criação de uma nova revisão. As próximas revisões também recebem automaticamente essa configuração, a menos que você faça atualizações explícitas para alterá-la.

Linha de comando

É possível definir públicos-alvo personalizados em um serviço usando o seguinte comando:

gcloud run services update SERVICE --add-custom-audiences=AUDIENCE

Substituir

SERVICE pelo nome do serviço do Cloud Run;
AUDIENCE por uma string do público-alvo personalizado que você quer permitir, como myservice ou https://myservice.example.com.

É possível remover todos os públicos-alvo personalizados a partir de um serviço usando o seguinte comando:

gcloud run services update SERVICE --clear-custom-audiences

YAML

Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Defina a anotação run.googleapis.com/custom-audiences nos metadados do serviço (não nos metadados template):
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE"]'
spec:
  template:
    ...
```
Substituir
- SERVICE pelo nome do serviço do Cloud Run;
- AUDIENCE por uma string do público-alvo personalizado que você quer permitir, como myservice ou https://myservice.example.com.
O valor do atributo é uma matriz JSON de strings entre aspas, o que exige o uso de aspas duplas e simples.
Substitua o serviço pela nova configuração usando o seguinte comando:
```
gcloud run services replace service.yaml
```

Como verificar públicos-alvo personalizados

Consiga um token de ID para uma conta de serviço que tenha permissão do IAM para invocar o serviço. Observe o uso do público-alvo personalizado AUDIENCE.
```
export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')
```
Substitua:
- SERVICE_ACCOUNT_EMAIL pelo e-mail da conta de serviço. Ele termina com .iam.gserviceaccount.com.
- AUDIENCE pelo valor do público-alvo personalizado que você definiu no serviço.
Chame o endpoint do serviço com esse token de ID
```
curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT
```
Substitua ENDPOINT pelo endpoint para acessar seu serviço, por exemplo, o domínio personalizado ou o URL .run.app.
Confirme se a solicitação está autorizada e se você vê a resposta esperada do serviço.