Públicos-alvo personalizados (serviços)

Esta página descreve como usar públicos-alvo personalizados para autorização. Defina públicos-alvo personalizados nos serviços do Cloud Run que não permitem acesso público (não autenticado) e estão recebendo solicitações por meio de um domínio 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, há vários cenários em que um serviço do Cloud Run pode estar atrás de um URL diferente do URL gerado padrão:

Um domínio personalizado é usado para acessar um serviço em que o cliente não esteja ciente do URL gerado pelo Google.
Vários serviços são implantados por trás de um balanceador de carga em que um cliente não consegue antecipar qual serviço regional é 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 o mesmo.

Nesses cenários, você precisa configurar um serviço para aceitar valores de público-alvo personalizados que permitem destinos adicionais conhecidos por um cliente. O URL padrão gerado pelo Google sempre permanecerá 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 está no nível de serviço e se aplica a todas as revisões de exibiçã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 bytes.

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 beta run services update SERVICE --add-custom-audiences=AUDIENCE

Substituir

SERVICE pelo nome do serviço do Cloud Run;
AUDIENCE com uma string para o público-alvo personalizado a que você quer dar suporte, como example.com ou aud1.

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

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

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 ver e fazer o download da configuração:

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","AUDIENCE2"]'
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    ...
```
Substituir
- SERVICE pelo nome do serviço do Cloud Run;
- AUDIENCE e AUDIENCE2 com strings para os públicos-alvo personalizados a que você quer dar suporte, por exemplo, example.com ou aud1
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 público 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.