Defina públicos-alvo personalizados para 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 pela gestão de identidade e acesso têm de fornecer um token de ID válido que inclua uma reivindicação de público-alvo correspondente ao URL *.run.app do serviço de receção. Para clientes que não conhecem este URL, pode usar um valor de público-alvo personalizado.

Compreender os públicos-alvo personalizados

O Cloud Run fornece uma função de invocador (roles/run.invoker) para suportar o controlo de acesso com a IAM. O controlo de acesso da IAM usa tokens de ID assinados pela Google, que são incluídos como símbolos da Web JSON (JWTs). Os conteúdos destes tokens estão em conformidade com uma norma OIDC.

Um campo de público-alvo é codificado no token para especificar o destino pretendido que pode usar o token. Isto limita o risco de um ataque de repetição, em que um token intercetado destinado a utilização com um serviço é repetido contra um serviço diferente.

Por convenção, o público-alvo é o URL completo do serviço de destino. Por predefinição, no Cloud Run, este é o URL gerado pela Google para um serviço que termina em run.app.

No entanto, um serviço do Cloud Run pode estar por detrás de um URL que não seja o URL gerado por predefinição, como nos seguintes cenários:

  • Quando usar um domínio personalizado para alcançar um serviço em que o cliente não tem conhecimento do URL gerado pela Google.
  • Quando implementa vários serviços atrás de um equilibrador de carga em que um cliente não consegue prever a que serviço regional um pedido chega. Os URLs gerados pela Google para serviços são específicos da região, mesmo que o nome do serviço seja o mesmo.

Nestes cenários, tem de configurar um serviço para aceitar valores de públicos-alvo personalizados que permitam alvos adicionais conhecidos por um cliente. O URL predefinido gerado pela Google permanece sempre como um valor de público-alvo aceite.

Defina e atualize públicos-alvo personalizados

A definição de públicos-alvo personalizados para o Cloud Run é feita ao nível do serviço e aplica-se a todas as revisões de publicação, de forma semelhante à subscrição de autorização da IAM.

Pode definir vários públicos-alvo personalizados, desde que a codificação JSON dos públicos-alvo como uma lista de strings não exceda 32 768 carateres.

Qualquer alteração de configuração leva à criação de uma nova revisão. As revisões subsequentes também vão receber automaticamente esta definição de configuração, a menos que faça atualizações explícitas para a alterar.

gcloud

Pode definir públicos-alvo personalizados num serviço através do seguinte comando:

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

Substituir

  • SERVICE com o nome do seu serviço do Cloud Run
  • AUDIENCE com uma string para o público-alvo personalizado que quer suportar, por exemplo, myservice ou https://myservice.example.com

Pode remover todos os públicos-alvo personalizados de um serviço através do seguinte comando:

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

YAML

  1. Se estiver a criar um novo serviço, ignore este passo. Se estiver a atualizar um serviço existente, transfira a respetiva configuração YAML:

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

  2. 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 com o nome do seu serviço do Cloud Run
    • AUDIENCE com uma string para o público-alvo personalizado que quer suportar, por exemplo, myservice ou https://myservice.example.com

    Tenha em atenção que o valor do atributo é uma matriz JSON de strings entre aspas, o que requer a utilização de aspas duplas e simples.

  3. Substitua o serviço pela respetiva nova configuração através do seguinte comando:

    gcloud run services replace service.yaml

Terraform

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

Adicione o seguinte a um recurso google_cloud_run_v2_service na sua configuração do Terraform:

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"

  custom_audiences = ["AUDIENCE"]
  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

Substituir:

  • SERVICE com o nome do seu serviço do Cloud Run.
  • REGION com a região Google Cloud . Por exemplo, europe-west1.
  • AUDIENCE com uma string para o público-alvo personalizado que quer suportar, por exemplo, myservice.

Validar públicos-alvo personalizados

  1. Obtenha um token de ID para uma conta de serviço que tenha autorização da IAM para invocar o serviço. Tenha em atenção a utilização do público-alvo personalizado AUDIENCE.

    export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')

    Substituir:

    • SERVICE_ACCOUNT_EMAIL com o email da conta de serviço. Termina com .iam.gserviceaccount.com.
    • AUDIENCE com o valor do público-alvo personalizado que definiu no serviço.

  2. Chame o ponto final do serviço com esse token de ID

    curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT

    Substitua ENDPOINT pelo ponto final para aceder ao seu serviço, por exemplo, o respetivo domínio personalizado ou URL .run.app.

  3. Confirme que o pedido está autorizado e que vê a resposta esperada do seu serviço.