Règle GenerateJWS

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Quoi

Génère un jeton JWS signé avec un ensemble de revendications configurable. Le jeton JWS 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.

Pour en savoir plus sur les composantes d'un jeton JWS ainsi que sur la façon dont elles sont chiffrées et signées, consultez le document RFC7515.

Vidéo

Regardez une courte vidéo pour apprendre à générer un jeton JWT signé. Bien que cette vidéo soit spécifique à la génération d'un jeton JWT, de nombreux concepts sont les mêmes pour JWS.

Exemples

• Générer un jeton JWS associé signé avec l'algorithme HS256
• Générer un jeton JWS dissocié signé avec l'algorithme RS256

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

Cet exemple de règle génère un jeton JWS associé et le signe à l'aide de l'algorithme HS256. L'algorithme HS256 repose sur une clé secrète partagée pour la signature et la validation de la signature.

Un jeton JWS associé contient l'en-tête encodé, la charge utile et la signature :

header.payload.signature

Définissez la valeur <DetachContent> sur "true" pour générer un contenu dissocié. Pour en savoir plus sur la structure et le format d'un jeton JWS, consultez la section Composantes d'un fichier JWS.

Utilisez l'élément <Payload> pour spécifier la charge utile JWS brute non encodée. Dans cet exemple, une variable contient la charge utile. Lorsque cette action de stratégie est déclenchée, Edge encode l'en-tête et la charge utile JWS, puis ajoute la signature encodée pour signer numériquement le JWS.

La configuration de règle ci-dessous crée un jeton JWS à partir d'une charge utile contenue dans la variable private.payload.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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

Cet exemple de règle génère un jeton JWS dissocié 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.

Un jeton JWS dissocié omet la charge utile du jeton JWS :

header..signature

Utilisez l'élément <Payload> pour spécifier la charge utile JWS brute non encodée. Lorsque cette règle est déclenchée, Edge encode l'en-tête et la charge utile JWS, puis les utilise pour générer la signature encodée. Cependant, le jeton JWS généré omet la charge utile. Il vous incombe de transmettre la charge utile à la règle VerifyJWS à l'aide de l'élément <DetachedContent> de cette règle.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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 JWS 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éments pour générer un jeton JWS

La documentation de référence des règles décrit les éléments et les attributs de la règle GenerateJWS.

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

<GenerateJWS name="JWS" 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.

<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 JWS.

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 au jeton JWS. 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 JWS. Exemple :

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

Spécifie s'il faut générer le jeton JWS avec une charge utile dissociée, <DetachContent>true</DetachContent>, ou non, <DetachContent>false</DetachContent>.

Si vous spécifiez "false", la valeur par défaut, le jeton JWS généré est au format suivant :

header.payload.signature

Si vous spécifiez "true" pour créer une charge utile dissociée, le jeton JWS généré omet la charge utile et se présente sous la forme suivante :

header..signature

Avec une charge utile dissociée, il vous appartient de transmettre la charge utile non codée d'origine à la règle CheckJWS à l'aide de l'élément <DetachedContent> de la stratégie.

<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).

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Indique où placer le jeton JWS généré par cette règle. Par défaut, celui-ci est placé dans la variable de flux jws.POLICYNAME.generated_jws.

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Spécifie la charge utile JWS brute non encodée. Indiquez une variable contenant la charge utile ou une chaîne.

<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 JWS. À 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 JWS. 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é (kid) à inclure dans l'en-tête d'un jeton JWS 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 une force de clé minimale pour les algorithmes HS256/HS384/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.

Variables de flux

La règle GenerateJWS ne définit pas de variables de flux.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>