Définir des audiences personnalisées (services)

Cette page explique comment utiliser des audiences personnalisées pour les autorisations.

Les clients qui appellent un service Cloud Run protégé par Identity and Access Management doivent fournir un jeton d'ID valide incluant une revendication d'audience correspondant à l'URL *.run.app du service destinataire. Pour les clients qui ne connaissent pas cette URL, vous pouvez utiliser une valeur d'audience personnalisée.

Comprendre les audiences personnalisées

Cloud Run fournit un rôle Demandeur (roles/run.invoker) pour assurer le contrôle des accès avec IAM. Le contrôle des accès IAM utilise des jetons d'ID signés par Google, qui sont empaquetés sous forme de jetons Web JSON (JWT). Le contenu de ces jetons est conforme à une norme OIDC.

Un champ d'audience est encodé dans le jeton pour spécifier la cible prévue pouvant l'utiliser. Cela limite le risque d'attaque de relecture, où un jeton intercepté destiné à être utilisé avec un service est réutilisé sur un autre service.

Par convention, l'audience est l'URL complète du service cible. Par défaut dans Cloud Run, il s'agit de l'URL générée par Google pour un service se terminant par run.app.

Toutefois, un service Cloud Run peut se trouver derrière une URL autre que l'URL générée par défaut, comme dans les scénarios suivants :

  • Lorsqu'un domaine personnalisé est utilisé pour accéder à un service où le client ne connaît pas l'URL générée par Google.
  • Lorsque plusieurs services sont déployés derrière un équilibreur de charge, où un client ne peut pas anticiper le service régional atteint par une requête. Les URL générées par Google pour les services sont spécifiques à une région, même si le nom du service est identique.

Dans de tels scénarios, vous devez configurer un service pour qu'il accepte des valeurs d'audience personnalisées qui permettent d'ajouter des cibles connues par un client. L'URL par défaut générée par Google reste toujours une valeur d'audience acceptée.

Définir et mettre à jour des audiences personnalisées

La définition d'audiences personnalisées pour Cloud Run s'applique au niveau du service et à toutes les révisions de diffusion, de la même manière que l'appartenance à une autorisation IAM.

Vous pouvez définir plusieurs audiences personnalisées tant que l'encodage JSON des audiences sous forme de liste de chaînes ne dépasse pas 32 768 caractères.

Tout changement de configuration entraîne la création d'une révision. Les révisions ultérieures obtiennent aussi automatiquement le même paramètre de configuration, à moins que vous ne le mettiez explicitement à jour.

gcloud

Vous pouvez définir des audiences personnalisées sur un service à l'aide de la commande suivante :

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

Remplacer

  • SERVICE par le nom de votre service Cloud Run
  • AUDIENCE par une chaîne pour l'audience personnalisée que vous souhaitez prendre en charge, par exemple myservice ou https://myservice.example.com

Vous pouvez supprimer toutes les audiences personnalisées d'un service à l'aide de la commande suivante :

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

YAML

  1. Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :

    gcloud run services describe SERVICE --format export > service.yaml
  2. Définissez l'annotation run.googleapis.com/custom-audiences sur les métadonnées du service (pas sur les métadonnées template) :

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
      annotations:
        run.googleapis.com/custom-audiences: '["AUDIENCE"]'
    spec:
      template:
        ...

    Remplacer

    • SERVICE par le nom de votre service Cloud Run
    • AUDIENCE par une chaîne pour l'audience personnalisée que vous souhaitez prendre en charge, par exemple myservice ou https://myservice.example.com

    Notez que la valeur de l'attribut est un tableau de chaînes JSON entre guillemets, nécessitant à la fois l'utilisation de guillemets doubles et simples.

  3. Remplacez le service par sa nouvelle configuration à l'aide de la commande suivante :

    gcloud run services replace service.yaml

Vérifier des audiences personnalisées

  1. Obtenez un jeton d'ID pour un compte de service autorisé à appeler le service. Notez l'utilisation de l'audience personnalisée AUDIENCE.

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

    Remplacez :

    • SERVICE_ACCOUNT_EMAIL par l'adresse e-mail du compte de service. Elle se termine par .iam.gserviceaccount.com.
    • AUDIENCE par la valeur d'audience personnalisée que vous avez définie sur le service.
  2. Appelez le point de terminaison du service avec ce jeton d'ID.

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

    Remplacez ENDPOINT par le point de terminaison pour accéder à votre service, par exemple son domaine personnalisé ou l'URL .run.app.

  3. Vérifiez que la requête est autorisée et que la réponse attendue de votre service s'affiche.