Utiliser Okta 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

  • 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é.

Comme expliqué dans le guide d'intégration d'Okta pour Google Cloud Endpoints, vous apportez les modifications suivantes à votre document OpenAPI :

  1. Ajoutez les éléments suivants à la définition de sécurité dans votre document OpenAPI. Remplacez YOUR_OKTA_TENANT_NAME par le nom de votre locataire Okta et YOUR_OKTA_CLIENT_ID par l'ID client que vous avez créé dans votre locataire Okta.

          securityDefinitions:
            okta_jwt:
              authorizationUrl: ""
              flow: "implicit"
              type: "oauth2"
              x-google-issuer: "https://YOUR_OKTA_TENANT_NAME.com"
              x-google-jwks_uri: "https://YOUR_OKTA_TENANT_NAME.com/oauth2/v1/keys"
              x-google-audiences: "YOUR_OKTA_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:
        - okta_jwt: []
    

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.

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. 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 l'objet JSON suivant :

{
  "id": "from-sub",
  "issuer": "from-iss",
  "email": "from-email",
  "audiences": ["from-aud"],
  "claims": {
     original-jwt-payload
   }
}

Si vous utilisez la version bêta d'ESPv2, le format de la valeur de l'en-tête est différent. Pour en savoir plus sur le nouveau format, consultez la page Migrer vers Extensible Service Proxy V2 bêta.

Étape suivante