Stratégie GenerateJWT

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Quoi

Génère un jeton JWT signé avec un ensemble de revendications configurable. Le jeton JWT peut ensuite être renvoyé aux clients, transmis à des cibles de backend ou être utilisé d'une autre manière. Consultez la section Présentation des règles JWS et JWT pour une présentation détaillée.

Vidéo

Regardez une courte vidéo pour apprendre à générer un jeton JWT signé.

Exemples

• Générer un jeton JWT signé avec l'algorithme HS256
• Générer un jeton JWT signé avec l'algorithme RS256

Générer un jeton JWT signé avec l'algorithme HS256

Cet exemple de stratégie génère un nouveau jeton JWT et le signe à l'aide de l'algorithme HS256. L'algorithme HS256 repose sur une clé secrète partagée à la fois pour signer et valider la signature.

Lorsque cette action de stratégie est déclenchée, Edge encode l'en-tête et la charge utile JWT, puis signe numériquement le JWT. Regardez la vidéo ci-dessus pour voir un exemple complet, y compris pour découvrir comment envoyer une demande à la stratégie.

La configuration de la stratégie créera un jeton JWT avec un ensemble de revendications standards telles que définies par la spécification JWT, y compris un délai d'expiration d'une heure, ainsi qu'une revendication supplémentaire. Vous pouvez inclure autant de revendications que vous le souhaitez. Consultez la documentation de référence sur les éléments pour en savoir plus sur les exigences et les options de chaque élément dans cet exemple de règle.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Le JWT obtenu contient cet en-tête…

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

… et disposera d'une charge utile avec du contenu qui ressemble à ceci :

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

La valeur des revendications iat, exp et jti varie.

Générer un jeton JWT signé avec l'algorithme RS256

Cet exemple de stratégie génère un nouveau jeton JWT et le signe à l'aide de l'algorithme RS256. La génération d'une signature RS256 repose sur une clé privée RSA, qui doit être fournie au format PEM. Regardez la vidéo ci-dessus pour voir un exemple complet, y compris pour découvrir comment envoyer une demande à la stratégie.

Lorsque cette action de stratégie est déclenchée, Edge encode et signe numériquement le JWT, y compris les revendications. Pour en savoir plus sur les composants d'un jeton JWT, ainsi que sur la façon dont ceux-ci sont chiffrés et signés, consultez le document RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Définir les éléments clé

Les éléments que vous utilisez pour spécifier la clé utilisée pour générer le jeton JWT dépendent de l'algorithme choisi, comme indiqué dans le tableau suivant :

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Référence d'élément pour générer un JWT

La documentation de référence des stratégies décrit les éléments et les attributs de la stratégie de génération de JWT.

Remarque : La configuration diffère légèrement selon l'algorithme de chiffrement que vous utilisez. Consultez les échantillons pour obtenir des exemples de configuration pour des cas d'utilisation spécifiques.

Attributs qui s'appliquent à l'élément de premier niveau

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

Les attributs suivants sont communs à tous les éléments parents de la stratégie.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Utilisez-le, en plus de l'attribut "name", pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Spécifie l'algorithme de chiffrement permettant de signer le jeton.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

La règle génère un jeton JWT contenant une revendication aud définie sur la valeur spécifiée. Cette revendication identifie les destinataires du jeton JWT. Il s'agit de l'une des revendications enregistrées et mentionnées dans le document RFC7519.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Permet de spécifier une ou plusieurs paires nom/valeur de revendication supplémentaires dans la charge utile du JWT. Vous pouvez spécifier explicitement la revendication sous forme de chaîne, d'un nombre, d'une valeur booléenne, d'un mappage ou d'un tableau. Un mappage est simplement un ensemble de paires nom/valeur.

L'élément <Claim> utilise les attributs suivants :

• name : (obligatoire) nom de la revendication.
• ref (facultatif) : nom d'une variable de flux. Si elle est présente, la règle utilise la valeur de cette variable comme revendication. Si un attribut ref et une valeur de revendication explicite sont spécifiés, la valeur explicite est la valeur par défaut, et est utilisée si la variable de flux référencée n'est pas résolue.
• type : (facultatif) au choix : chaîne (par défaut), nombre, valeur booléenne ou mappage
• array : (facultatif) défini sur true pour indiquer que la valeur est un tableau de types. Valeur par défaut : "false".

Lorsque vous incluez l'élément <Claim>, les noms des revendications sont définis de manière statique lorsque vous configurez la règle. Vous pouvez également transmettre un objet JSON afin de spécifier les noms des revendications. L'objet JSON étant transmis en tant que variable, les noms de revendication dans le jeton JWT généré sont déterminés au moment de l'exécution.

Exemple :

<AdditionalClaims ref='json_claims'/>

Où la variable json_claims contient un objet JSON au format :

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

Le jeton JWT généré inclut toutes les revendications de l'objet JSON.

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Place les paires nom/valeur de revendication supplémentaires dans l'en-tête du jeton JWT.

L'élément <Claim> utilise les attributs suivants :

• name : (obligatoire) nom de la revendication.
• ref (facultatif) : nom d'une variable de flux. Si elle est présente, la règle utilise la valeur de cette variable comme revendication. Si un attribut ref et une valeur de revendication explicite sont spécifiés, la valeur explicite est la valeur par défaut, et est utilisée si la variable de flux référencée n'est pas résolue.
• type : (facultatif) au choix : chaîne (par défaut), nombre, valeur booléenne ou mappage
• array : (facultatif) défini sur true pour indiquer que la valeur est un tableau de types. Valeur par défaut : "false".

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Ajoute l'en-tête critique crit à l'en-tête JWT. L'en-tête crit est un tableau de noms d'en-têtes qui doivent être connus et reconnus par le destinataire du jeton JWT. Exemple :

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Au moment de l'exécution, la stratégie VerifyJWT examine l'en-tête crit. Pour chaque élément répertorié dans l'en-tête crit, celle-ci vérifie que l'élément <KnownHeaders> de la stratégie VerifyJWT répertorie également cet en-tête. Tout en-tête identifié par la stratégie VerifyJWT dans crit et qui ne figure pas encore dans le fichier <KnownHeaders> entraîne l'échec de la stratégie VerifyJWT.

<CustomClaims>

Remarque : Actuellement, un élément CustomClaims est inséré lorsque vous ajoutez une nouvelle règle GenerateJWT via l'interface utilisateur. Cet élément n'est pas fonctionnel et est ignoré. L'élément correct à utiliser à la place est <AdditionalClaims>. L'interface utilisateur sera mise à jour pour insérer les éléments corrects ultérieurement.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

Spécifie la durée de vie du JWT en millisecondes, secondes, minutes, heures ou jours.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Génère un jeton JWT avec la revendication jti spécifique. Lorsque la valeur textuelle et l'attribut "ref" sont tous deux vides, la règle génère un jti contenant un UUID aléatoire. La revendication de l'ID JWT (jti) est un identifiant unique du jeton JWT. Pour en savoir plus sur jti, consultez le document RFC7519.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Définissez la valeur sur "false" si vous souhaitez que la règle génère une erreur lorsqu'une variable référencée dans la règle ne peut être résolue. Définissez la valeur sur "true" pour traiter toute variable irrésolue comme une chaîne vide (null).

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

La règle génère un jeton JWT contenant une revendication portant le nom iss, avec une valeur définie sur la valeur spécifiée. C'est une revendication qui identifie l'émetteur du jeton JWT. Il s'agit d'un ensemble de revendications enregistrées et mentionnées dans le document RFC7519.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Indique l'heure à laquelle le jeton devient valide. Le jeton n'est pas valide avant l'heure spécifiée. Vous pouvez spécifier une valeur temporelle absolue ou une heure en fonction du moment où le jeton est généré.

Valeurs de temps valides pour l'élément NotBefore pour les valeurs de délai absolu

Pour les valeurs de délai relatif, spécifiez un entier et une période, par exemple :

• 10 s
• 60 min
• 12 h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Indique où placer le jeton JWT généré par cette stratégie. Par défaut, celui-ci est placé dans la variable de flux jwt.POLICYNAME.generated_jwt.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Spécifie l'ID de clé (enfant) à inclure dans l'en-tête JWT. À n'utiliser que lorsque l'algorithme est RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Indiquez le mot de passe que la règle doit utiliser pour déchiffrer la clé privée, si nécessaire. Utilisez l'attribut ref pour transmettre la clé dans une variable de flux. À n'utiliser que lorsque l'algorithme est RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Spécifie une clé privée encodée au format PEM utilisée pour signer le jeton JWT. Utilisez l'attribut "ref" pour transmettre la clé dans une variable de flux. À n'utiliser que lorsque l'algorithme est RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Spécifie l'ID de clé (enfant) à inclure dans l'en-tête JWT d'un jeton JWT signé avec un algorithme HMAC. Utilisez ce paramètre uniquement lorsque l'algorithme est HS256/HS384/HS512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Fournit la clé secrète utilisée pour vérifier ou signer les jetons avec un algorithme HMAC. À n'utiliser que lorsque l'algorithme est HS256/HS384/HS512. Utilisez l'attribut ref pour transmettre la clé dans une variable de flux.

Edge applique un niveau de sécurité de clé minimal pour les algorithmes HS256, HS384 et HS512. La longueur de clé minimale pour HS256 est de 32 octets, pour HS384 de 48 octets, et pour HS512 de 64 octets. L'utilisation d'une clé d'un niveau de sécurité inférieur entraîne une erreur d'exécution.

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

Exemple :

<Subject ref="apigee.developer.email"/>

La stratégie génère un jeton JWT contenant une revendication sub, définie sur la valeur spécifiée. Cette revendication identifie le sujet du jeton JWT ou donne une instruction le concernant. Il s'agit de l'ensemble standard de revendications mentionné dans le document RFC7519.

Variables de flux

La stratégie de génération d'un JWT ne définit pas de variables de flux.

Informations de référence sur les erreurs

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

Pour le traitement des erreurs, la meilleur pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

Exemple de règle de défaillance

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>