Règle GenerateJWS

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur 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 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 règle 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, et les utilise ensuite 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 :

Algorithme Éléments clés
HS{256/384/512}*
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512}*
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Les éléments <Password> et <Id> sont facultatifs.

* Pour en savoir plus sur les conditions requises par les clés, consultez la section À propos des algorithmes de chiffrement de signature.

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.

Attribut Description Par défaut Présence
nom Nom interne de la stratégie. Les caractères que vous pouvez utiliser dans le nom se limitent à : A-Z0-9._\-$ %. Cependant, l'interface utilisateur de gestion Edge applique des telles que la suppression automatique de caractères qui ne sont pas alphanumériques.

Vous pouvez également utiliser l'élément <displayname></displayname> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

ND Requis
continueOnError Définissez sur false pour afficher une erreur en cas d'échec d'une stratégie. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle.

faux Facultatif
activé Définissez la valeur sur true pour appliquer la stratégie.

Définissez la valeur sur false pour "désactiver" la stratégie. La stratégie ne sera pas appliquée même si elle reste associée à un flux.

vrai Facultatif
async Cet attribut est obsolète. faux Obsolète

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

Par défaut Si vous omettez cet élément, la valeur de l'attribut de nom de la stratégie est utilisée.
Présence Facultatif
Type Chaîne

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

Par défaut N/A
Présence Requis
Type Chaîne
Valeurs valides HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

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

Par défaut N/A
Présence Facultatif
Valeurs valides Toute valeur que vous souhaitez utiliser dans une revendication supplémentaire. 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.

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.

Par défaut N/A
Présence Facultatif
Type Tableau de chaînes séparées par une virgule
Valeurs valides Tableau ou nom d'une variable contenant le tableau.

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

Par défaut false
Présence Facultatif
Type Booléen
Valeurs valides True ou False

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

Par défaut false
Présence Facultatif
Type Booléen
Valeurs valides true ou false

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

Par défaut jws.POLICYNAME.generated_jws
Présence Facultatif
Type Chaîne (nom de variable de flux)

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

Par défaut N/A
Présence Requis
Type Chaîne, tableau d'octets, flux ou toute autre représentation de la charge utile JWS non encodée

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

Par défaut N/A
Présence Facultatif
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

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

Par défaut N/A
Présence Facultatif
Type Chaîne
Valeurs valides Référence de variable de flux

Remarque : Vous devez spécifier une variable de flux. Edge rejettera comme non valide un Configuration de stratégie dans laquelle le mot de passe est spécifié en texte brut. La variable de flux doit comporter le préfixe "private". Par exemple, private.mypassword.

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

Par défaut N/A
Présence Obligatoire pour générer un jeton JWS à l'aide de l'algorithme RS256.
Type Chaîne
Valeurs valides Variable de flux contenant une chaîne représentant une valeur de clé privée RSA encodée au format PEM.

Remarque : La variable de flux doit comporter le préfixe "private". Par exemple, private.mykey.

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

Par défaut N/A
Présence Facultatif
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

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

Par défaut N/A
Présence Obligatoire pour les algorithmes HMAC.
Type Chaîne
Valeurs valides Variable de flux faisant référence à une chaîne

Remarque : Si une variable de flux, elle doit comporter le préfixe "private". Par exemple, private.mysecret

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.

Code d'erreur État HTTP Se produit quand
steps.jws.GenerationFailed 401 La règle n'a pas pu générer le jeton JWS.
steps.jws.InsufficientKeyLength 401 Pour une clé inférieure à 32 octets pour l'algorithme HS256
steps.jws.InvalidClaim 401 en cas de revendication ou de non-concordance des revendications, ou si un en-tête ou un en-tête est manquant.
steps.jws.InvalidCurve 401 La courbe spécifiée par la clé n'est pas valide pour l'algorithme à courbe elliptique.
steps.jws.InvalidJsonFormat 401 JSON non valide trouvé dans l'en-tête JWS.
steps.jws.InvalidPayload 401 La charge utile JWS n'est pas valide.
steps.jws.InvalidSignature 401 <DetachedContent> est omis et le jeton JWS possède une charge utile de contenu dissociée.
steps.jws.KeyIdMissing 401 La règle de validation utilise un JWKS comme source pour les clés publiques, mais le JWS signé n'inclut pas de propriété kid dans l'en-tête.
steps.jws.KeyParsingFailed 401 Impossible d'analyser la clé publique à partir des informations de clé fournies.
steps.jws.MissingPayload 401 La charge utile JWS est manquante.
steps.jws.NoAlgorithmFoundInHeader 401 Cette erreur produit lorsque le jeton JWS omet l'en-tête de l'algorithme.
steps.jws.SigningFailed 401 Dans GenerateJWS, pour une clé inférieure à la taille minimale des algorithmes HS384 ou HS512
steps.jws.UnknownException 401 Une exception inconnue s'est produite.
steps.jws.WrongKeyType 401 Type de clé spécifié incorrect. Par exemple, si vous spécifiez une clé RSA pour un algorithme à courbe elliptique ou une clé à courbe elliptique pour un algorithme RSA.

Erreurs de déploiement

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

Nom de l'erreur Se produit quand
InvalidAlgorithm Les seules valeurs valides sont : RRS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Autres erreurs de déploiement possibles.

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.

Variables Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "TokenExpired"
JWS.failed Toutes les règles JWS définissent la même variable en cas d'échec. jws.JWS-Policy.failed = true

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>