Utiliser Auth0 pour authentifier les utilisateurs

Cette page explique la compatibilité de l'authentification des utilisateurs dans Cloud Endpoints.

Pour authentifier un utilisateur, une application cliente doit envoyer un jeton Web JSON (JWT) dans l'en-tête d'autorisation de la requête HTTP envoyée à votre API backend. Le proxy ESP (Extensible Service Proxy) valide le jeton pour le compte de votre API. Vous n'avez donc pas besoin d'ajouter de code pour traiter l'authentification. Cependant, vous devez configurer votre document OpenAPI pour qu'il soit compatible avec les méthodes d'authentification que vous avez choisies.

ESP valide un jeton JWT de manière optimale à l'aide des clés publiques de l'émetteur de jetons JWT. ESP met en cache les clés publiques pendant cinq minutes. De plus, les jetons JWT validés avec succès sont aussi mis en cache par ESP pendant cinq minutes ou jusqu'à leur expiration, selon la première limite atteinte.

Avant de commencer

  • Ajoutez un code d'authentification à l'application cliente en suivant les instructions de la documentation sur Auth0.

  • Lorsqu'une application cliente envoie une requête HTTP, l'en-tête d'autorisation de la requête doit contenir les revendications suivantes :
    • iss (émetteur)
    • sub (objet)
    • aud (cible)
    • iat (date/heure d'émission)
    • exp (date/heure d'expiration)

Configurer ESP pour l'authentification client

Vous devez disposer d'un objet d'exigences de sécurité et d'un objet de définitions de sécurité dans le document OpenAPI pour que le proxy ESP puisse valider les revendications dans le jeton JWT signé.

Pour l'authentification Auth0 :

  1. Ajoutez les éléments suivants à la définition de sécurité dans votre document OpenAPI :

      securityDefinitions:
    auth0_jwk:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      # Replace YOUR-ACCOUNT-NAME with your Auth0 account name.
      x-google-issuer: "https://YOUR-ACCOUNT-NAME.auth0.com/"
      x-google-jwks_uri: "https://YOUR-ACCOUNT-NAME.auth0.com/.well-known/jwks.json"
      # Optional. Replace YOUR-CLIENT-ID with your client ID
      x-google-audiences: "YOUR-CLIENT-ID"

  2. Ajoutez une section de sécurité au niveau de l'API pour une application à l'ensemble de l'API, ou au niveau de la méthode pour une application à une méthode spécifique.

      security:
    - auth0_jwk: []

Vous pouvez établir plusieurs définitions de sécurité dans le document OpenAPI, mais l'émetteur doit être différent pour chaque définition. Notez que, si vous utilisez des sections de sécurité au niveau de l'API et au niveau de la méthode, les paramètres au niveau de l'API seront ignorés.

Le champ x-google-audiences n'est pas obligatoire. ESP accepte tous les jetons JWT avec le nom du service de backend sous la forme https://SERVICE_NAME dans la revendication aud. Pour autoriser des ID clients supplémentaires à accéder au service de backend, vous pouvez spécifier les ID clients autorisés dans le champ x-google-audiences à l'aide de valeurs séparées par des virgules. ESP accepte ensuite les jetons JWT comportant dans la revendication aud les ID clients spécifiés.

Vous pouvez également personnaliser les emplacements JWT en ajoutant x-google-extensions. Pour en savoir plus, consultez la page Extensions OpenAPI.

Effectuer un appel authentifié à une API Endpoints

Par mesure de sécurité, lorsque vous envoyez une requête à l'aide d'un jeton d'authentification, nous vous recommandons de placer le jeton d'authentification dans l'en-tête Authorization:Bearer. Exemple :

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

Ici, ENDPOINTS_HOST et TOKEN sont des variables d'environnement contenant respectivement le nom d'hôte de l'API et le jeton d'authentification. Consultez la section Effectuer une requête authentifiée à une API Endpoints pour obtenir un exemple de code qui envoie une requête à l'aide de l'en-tête Authorization:Bearer.

Si vous ne pouvez pas utiliser l'en-tête lors de l'envoi de la requête, vous pouvez placer le jeton d'authentification dans un paramètre de requête appelé access_token. Par exemple :

curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Recevoir les résultats authentifiés dans votre API

ESP transfère généralement tous les en-têtes reçus. Cependant, il remplace l'en-tête Authorization d'origine lorsque l'adresse de backend est spécifiée par x-google-backend dans la spécification OpenAPI ou BackendRule dans la configuration du service gRPC.

ESP envoie le résultat de l'authentification dans le champ X-Endpoint-API-UserInfo à l'API backend. Nous vous recommandons d'utiliser cet en-tête à la place de l'en-tête Authorization d'origine. Cet en-tête est une chaîne qui définit un encodage base64url d'un objet JSON. Le format de l'objet JSON diffère entre ESPv2 et ESP. Pour ESPv2, l'objet JSON correspond exactement à la charge utile JWT d'origine. Pour ESP, l'objet JSON utilise des noms de champ différents et place la charge utile JWT d'origine sous le champ claims. Pour en savoir plus sur le format, consultez la section Gérer les jetons JWT dans le service de backend.

Exemples

Étapes suivantes