Utiliser JWT pour authentifier les utilisateurs

Cette page explique comment prendre en charge l'authentification des utilisateurs dans API Gateway.

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. API Gateway valide le jeton au nom de votre API, de sorte que vous n'ayez pas à ajouter de code dans votre API pour traiter l'authentification. Vous devez toutefois configurer Configuration d'API pour votre passerelle afin qu'elle soit compatible avec les méthodes d'authentification de votre choix.

API Gateway valide un jeton JWT de manière optimale à l'aide du jeton JWT. l'ensemble de clés Web JSON (JWKS) de l'émetteur. L'emplacement du fichier JWKS est spécifié dans le champ x-google-jwks_uri de la configuration de l'API de la passerelle. API Gateway met en cache les JWKS pendant cinq minutes et l'actualise toutes les cinq minutes.

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 API Gateway 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 votre configuration d'API pour que API Gateway valide les revendications dans le jeton JWT signé.

Pour l'authentification JWT :

  1. Ajoutez les éléments suivants à la définition de sécurité dans la configuration de votre API, qui suit le schéma de sécurité OpenAPI 2.0 :

     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 définir plusieurs définitions de sécurité dans la configuration de l'API, mais chaque doit avoir un émetteur différent. 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. API Gateway accepte tous les jetons JWT avec le nom du service de backend sous la forme suivante : https://SERVICE_NAME dans la revendication aud.

Pour autoriser des ID client supplémentaires à accéder au service de backend, vous pouvez spécifier le paramètre d'identifiants clients autorisés dans le champ x-google-audiences en utilisant des valeurs séparées par une virgule. API Gateway accepte ensuite les jetons JWT avec n'importe lequel des les numéros clients spécifiés dans la revendication aud.

Le champ x-google-jwks_uri est obligatoire. API Gateway 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.

Effectuer un appel authentifié à une API API Gateway

Lorsque vous envoyez une requête à l'aide d'un jeton d'authentification, nous vous recommandons de placer ce jeton dans l'en-tête Authorization:Bearer. Exemple :

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

Ici, GATEWAY_URL et TOKEN sont des variables d'environnement contenant respectivement l'URL de la passerelle déployée et le jeton d'authentification. Voir Envoyez une requête authentifiée à une API API Gateway 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 "${GATEWAY_URL}/echo?access_token=${TOKEN}"

Recevoir les résultats authentifiés dans votre API

API Gateway transfère généralement tous les en-têtes reçus. Toutefois, elle remplace en-tête Authorization d'origine lorsque l'adresse du backend est spécifiée par x-google-backend dans la configuration de l'API.

API Gateway envoie le résultat de l'authentification dans le champ X-Apigateway-Api-Userinfo à l'API backend. Il est recommandé d'utiliser cet en-tête à la place de l'en-tête Authorization d'origine. Cet en-tête est encodé en base64url et contient la charge utile JWT.

Étape suivante