Utiliser une méthode personnalisée 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 la documentation du fournisseur d'authentification.

  • 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 personnalisée :

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

     securityDefinitions:
   your_custom_auth_id:
     authorizationUrl: ""
     flow: "implicit"
     type: "oauth2"
     # The value below should be unique
     x-google-issuer: "issuer of the token"
     x-google-jwks_uri: "url to the public key"
     # 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:
   - your_custom_auth_id: []

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.

ESP accepte deux formats de clé publique asymétrique définis par l'extension OpenAPI x-google-jwks_uri :

  • Le format prédéterminé JWK Exemple : 
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Exemple : 
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Si vous utilisez un format de clé symétrique, définissez x-google-jwks_uri sur l'URI d'un fichier contenant la chaîne de clé encodée en base64url.

Si vous omettez x-google-jwks_uri, ESP suivra le protocole OpenID Connect Discovery pour détecter automatiquement l'URI JWKS pour le fournisseur OpenID indiqué. ESP envoie une requête à x-google-issuer/.well-known/openid-configuration, analyse la réponse JSON et lit l'URI JWKS à partir du champ de premier niveau jwks_uri.

Notez que l'omission de x-google-jwks_uri entraîne des temps de démarrage à froid plus élevés, car ESP doit effectuer un appel distant supplémentaire au démarrage. Par conséquent, il est recommandé d'omettre ce champ si l'URI JWKS change souvent. La plupart des fournisseurs OpenID certifiés (tels que Google, Auth0 et Okta) possèdent des URI JWKS stables.

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.

Étape suivante