Utiliser des jetons OAuth JWT

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Cet article explique comment générer, valider et actualiser des jetons d'accès JWT à l'aide de la règle OAuthV2.

Présentation

Les opérations JWT permettent à la règle OAuthV2 de générer, de valider et d'actualiser des jetons d'accès conformes à la norme IETF RFC 9068, qui décrit comment émettre des jetons d'accès au format JWT. Les jetons JWT sont couramment utilisés pour partager des revendications ou des assertions entre des applications connectées. L'émission de jetons d'accès OAuthV2 au format JWT est une alternative à l'émission de jetons d'accès opaques.

Lorsqu'elle est configurée pour un jeton JWT, la règle OAuthV2 génère et renvoie un jeton JWT encodé en base64 qui consiste en un en-tête, une charge utile et une signature séparée par des points. Exemple :

**Figure 1** : Format sérialisé JWT composé d'un en-tête, d'une charge utile et d'une signature séparés par des points.

Le contenu encodé de ces éléments dépend de la manière dont vous configurez la règle OAuthV2. Dans la règle, vous spécifiez des paramètres tels que l'algorithme de signature et les éléments de charge utile tels que l'objet et le nom. Par exemple, l'en-tête peut être décodé en tant que {"alg":"HS256","typ":"at+JWT"} et la charge utile peut être décodée en tant que {"sub":"ABC1234567","iat":1516239022}.

L'en-tête spécifie une revendication typ (toujours "at+JWT) et une revendication alg, indiquant l'algorithme utilisé pour signer le jeton JWT. Apigee est compatible avec les algorithmes RSA et HMAC : RS(256, 384, 512) et HS(256, 384, 512).

Charge utile

La charge utile comprend des revendications concernant l'entité. Certaines revendications doivent être fournies dans la configuration de la règle, tandis que d'autres sont générées automatiquement par l'environnement d'exécution Apigee. La règle accepte les revendications suivantes :

Revendication	Description	Fourni par
`iss`	Émetteur de jeton. Cette valeur est définie comme suit : `(http\|https)://{domain-name-for-proxy}/{proxy-basePath}`. Exemple : `https://api.mycompany.com/auth/v2`	Apigee
`sub`	ID client ou ID du propriétaire de la ressource (dans le cas de types d'attribution de mots de passe ou d'autorisation). Si le paramètre `appEndUserId` est fourni dans la requête, cette valeur est utilisée comme ID de propriétaire de la ressource. Vous pouvez contrôler l'emplacement où cette valeur est définie à l'aide de l'élément `<AppEndUser>` de la règle OAuthV2.	Développeur d'API
`jti`	ID unique, représenté sous forme de chaîne aléatoire sauvegardée par UUID pour identifier de manière unique le jeton.	Apigee
`exp`	Délai d'expiration, c'est-à-dire le délai au terme duquel le jeton doit être considéré comme non valide. La valeur est exprimée en epoch (en secondes).	Apigee
`iat`	Date/Heure d'émission : heure de création du jeton. La valeur est exprimée en epoch (en secondes).	Apigee
`client_id`	Identifiant unique de l'application cliente.	Développeur d'API
`scope`	Champ d'application OAuth attribué au jeton. Consultez également la section Utiliser les champs d'application OAuth.	Développeur d'API

Signature

La signature est générée à l'aide de l'en-tête encodé, de la charge utile, de la clé secrète/privée et de l'algorithme. La signature permet de garantir que le contenu du jeton n'a pas été altéré.

Pour en savoir plus sur les jetons d'accès OAuth 2.0 au format JWT, consultez IETF RFC 9068 : profil des jetons Web JSON (JWT) pour les jetons d'accès OAuth 2.0.

Prérequis

Dans ce document, nous partons du principe que vous savez comment générer et valider les jetons d'accès OAuthV2 à l'aide de la règle OAuthV2. Que vous utilisiez les opérations JWT ou les opérations traditionnelles qui créent des jetons de chaîne opaque, l'utilisation de base de la règle OAuthV2 est identique. Vous pouvez utiliser des jetons d'accès JWT avec tous les types d'attribution OAuthV2 compatibles. Consultez également la page Présentation d'OAuth 2.0.

Génération en cours

Utilisez les opérations GenerateJWTAccessToken et GenerateJWTAccessTokenImplicitGrant pour générer un jeton d'accès JWT avec la règle OAuthV2. Ces opérations sont semblables aux opérations GenerateAccessToken et GenerateAccessTokenImplicitGrant traditionnelles de la règle. La principale différence est que l'opération JWT renvoie un jeton d'accès au format JWT au lieu d'un jeton de chaîne opaque. Consultez également la section Obtenir des jetons OAuth 2.0.

Les exemples suivants montrent comment utiliser ces opérations dans la règle OAuthV2. Les exemples utilisent le type d'attribution client_credentials. Cependant, vous pouvez utiliser n'importe quel type d'attribution compatible avec ces opérations.

Générer un jeton au format JWT signé avec un algorithme HMAC

Spécifiez l'élément <Algorithm> avec l'un des algorithmes HMAC (HS256/HS384/HS512). Indiquez également le <SecretKey>. L'exemple suivant montre une règle configurée pour générer un jeton JWT signé avec l'algorithme HS512, à l'aide de la clé secrète spécifiée.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Générer un jeton au format JWT signé avec un algorithme RSA

Spécifiez l'un des algorithmes RSA (RS256/RS384/RS512) dans l'élément <Algorithm> et indiquez la clé privée dans l'élément <PrivateKey>. L'exemple suivant montre une règle configurée pour générer un jeton JWT signé avec une clé privée RSA à l'aide de l'algorithme RS256.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Générer un jeton au format JWT avec le type d'attribution implicite

L'opération GenerateJWTAccessTokenImplicitGrant génère un jeton d'accès JWT à l'aide du type d'attribution implicite. Cette action attribue automatiquement au jeton le type d'attribution implicite. Par conséquent, l'élément <SupportedGrantTypes> n'est pas obligatoire. Comme il s'agit d'un jeton JWT, l'élément <Algorithm> est obligatoire. L'exemple suivant illustre l'utilisation de l'algorithme RS256. De ce fait, l'élément <PrivateKey> est obligatoire. Consultez également Utiliser le type d'attribution implicite.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Validation

Utilisez l'opération VerifyJWTAccessToken pour vérifier un jeton d'accès JWT avec la règle OAuthV2. Cette opération est semblable à l'opération VerifyAccessToken, à la différence que VerifyJWTAccessToken s'applique aux jetons au format JWT, tandis que VerifyAccessToken s'applique aux jetons opaques.

Valider un jeton d'accès JWT signé avec un algorithme HMAC

L'exemple suivant montre comment configurer la règle OAuthV2 afin de vérifier un jeton JWT signé avec l'algorithme HS512. Lorsque vous utilisez l'opération VerifyJWTAccessToken avec un algorithme HMAC, la configuration de la règle doit utiliser l'élément <SecretKey> pour spécifier la clé secrète utilisée pour signer le jeton JWT.

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

Valider un jeton d'accès JWT signé avec un algorithme RSA

L'exemple suivant montre comment configurer la règle OAuthV2 afin de vérifier un jeton JWT signé avec l'algorithme RS512. Lorsque vous utilisez l'opération VerifyJWTAccessToken avec un algorithme RSA, la configuration de la règle doit utiliser l'élément <PublicKey> pour spécifier la clé publique correspondant à la clé privée utilisée pour signer le jeton JWT.

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

Actualisation

Utilisez l'opération RefreshJWTAccessToken pour actualiser un jeton d'accès JWT. Cette opération est semblable à l'opération RefreshAccessToken traditionnelle de la règle. Consultez également la section Actualiser un jeton d'accès.

Actualiser un jeton d'accès signé avec HMAC

L'exemple XML suivant montre comment configurer la règle OAuthV2 pour actualiser un jeton JWT signé avec un algorithme HMAC. Dans ce cas, les éléments <SecretKey> et <Algorithm> sont obligatoires.

La réponse de l'opération d'actualisation est semblable à la réponse d'un jeton nouvellement généré. L'opération d'actualisation génère un nouveau jeton JWT avec un délai d'expiration mis à jour, sans modifier les autres revendications.

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Actualiser un jeton d'accès JWT signé avec RSA

L'exemple XML suivant montre comment configurer la règle OAuthV2 pour actualiser un jeton JWT signé avec un algorithme RSA. Consultez également la section Actualiser un jeton d'accès.

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Exemple de réponse de jeton

Pour les opérations de génération et d'actualisation, le corps de la réponse est semblable à l'exemple suivant. Notez que le jeton access_token est représenté sous forme de jeton JWT sérialisé, et que le jeton d'actualisation est un jeton au format opaque traditionnel.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

Résumé des éléments de règle requis

Le tableau suivant décrit les éléments spécifiques au jeton JWT utilisés dans les exemples précédents :

Élément	Type	Remarques
Algorithme	Valeur statique	Spécifie l'algorithme utilisé pour signer le jeton.
SecretKey	Valeur référencée	Fournit la clé secrète utilisée pour vérifier ou signer les jetons avec un algorithme HMAC : HS (256/384/512).
PrivateKey	Valeur référencée	Fournit la clé privée utilisée pour générer le jeton. À n'utiliser que lorsque l'algorithme est un algorithme RSA : RS (256/384/512).
PublicKey	Valeur référencée	Fournit la clé publique utilisée pour vérifier le jeton. À n'utiliser que lorsque l'algorithme est un algorithme RSA : RS (256/384/512).

Éléments de règle non compatibles

Les éléments de règle OAuthV2 suivants ne sont pas compatibles avec les configurations de jeton JWT :

Élément	Remarques
ExternalAuthorization	Lors de la génération d'un jeton d'accès JWT, la règle OAuthV2 valide l'ID client et le secret.
ExternalAccessToken	Lors de la génération d'un jeton d'accès JWT, le jeton est signé par Apigee et les revendications sont fournies par défaut par Apigee ou via la configuration des règles. La règle est compatible avec `ExternalRefreshToken`, ce qui peut faciliter les cas d'utilisation de la migration.
RFCCompliantRequestResponse	La génération et l'actualisation des jetons d'accès JWT sont conformes à la norme RFC par défaut.

Remarques sur l'utilisation

Les jetons JWT chiffrés ne sont pas acceptés.
En plus d'un jeton d'accès JWT, la réponse de la règle inclut également un jeton d'actualisation opaque pour les types d'attribution dans lesquels les jetons d'actualisation sont disponibles. Seuls les types d'attribution de mots de passe et de code d'authentification sont compatibles avec les jetons d'actualisation.
Incluez l'en-tête "Authorization" dans les requêtes envoyées au proxy contenant la règle OAuthV2.
Vous ne pouvez pas révoquer un jeton d'accès JWT. Le jeton JWT généré restera valide jusqu'à son expiration. Vous pouvez révoquer un jeton d'actualisation associé à un jeton d'accès JWT.
La génération, la vérification et l'actualisation des jetons d'accès doivent être gérées par Apigee. Bien qu'une application ou une passerelle externe ayant accès à la clé publique ou secrète puisse décoder le contenu du jeton JWT, l'application externe ne dispose pas d'informations sur les produits d'API identifiés par la valeur client_id et ne peut donc pas jouer un rôle dans l'autorisation du proxy d'API.