Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
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.
Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.
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 JWS signé avec HS256
Cet exemple de règle génère un JWS signé avec l'algorithme HS256. L'algorithme HS256 repose sur une clé secrète partagée pour la signature et la validation de la signature. Ce JWS utilise du contenu "attaché", ce qui signifie que l'en-tête encodé, la charge utile et la signature sont concaténés par points pour produire le JWS final :
[header].[payload].[signature]
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 règle est déclenchée, Apigee encode l'en-tête et la charge utile JWS, puis ajoute la signature encodée pour signer numériquement le jeton JWS.
La configuration de règle ci-dessous crée un JWS à partir d'une charge utile contenue dans la variable my-payload et stocke le JWS obtenu dans la variable output-variable.
<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="my-payload"/> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
Générer un JWT signé HS256
Cet exemple génère également un JWS avec du contenu associé et signé avec l'algorithme HS256. Dans ce cas, la charge utile est JSON. La définition de l'en-tête typ dans JWT génère un JWS signé qui est également un JWT signé.
(référence)
La configuration de règle ci-dessous crée un JWS à partir d'une charge utile contenue dans la variable json-content et stocke le JWS obtenu dans la variable output-variable. Le résultat est un JWT signé si, et seulement si, la variable json-content contient une charge utile JSON et que les propriétés de cette charge utile JSON sont valides pour JWT. Par exemple, la propriété exp, si elle est présente, doit contenir une valeur numérique. La propriété aud, si elle est présente, doit être une chaîne ou un tableau de chaînes. Et ainsi de suite. Pour en savoir plus sur les valeurs valides pour les revendications JWT, consultez le document IETF RFC7519.
<GenerateJWS name="JWS-Generate-HS256-JWT"> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <Payload ref="json-content"/> <AdditionalHeaders> <Claim name="typ">JWT</Claim> </AdditionalHeaders> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
Générer un JWS dissocié
Cet exemple génère une requête JWS avec un contenu dissocié, signé avec 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 JWS avec un contenu dissocié omet la charge utile du JWS généré :
[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, Apigee encode l'en-tête et la charge utile JWS, puis les utilise pour générer la signature encodée. Toutefois, le JWS généré omet la charge utile encodée du JWS sérialisé. Cela s'avère utile lorsque le contenu signé est volumineux, binaire (image ou PDF, par exemple) ou les deux. Pour autoriser la validation, vous devez transmettre les deux éléments, le JWS et la charge utile inclus dans le contenu signé, à la partie de validation. Si vous utilisez la règle VerifyJWS pour vérifier le JWS, vous pouvez spécifier la variable contenant la charge utile avec l'élément <DetachedContent> de la règle VerifyJWS.
<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="my-payload"/> <DetachContent>true</DetachContent> <OutputVariable>output-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 |
|
| * 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._\-$ %. L'interface utilisateur Apigee applique cependant des restrictions supplémentaires, telles que la suppression automatique des caractères qui ne sont pas alphanumériques.
Vous pouvez également utiliser l'élément |
N/A | 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 |
faux | Facultatif |
| activé | Définissez la valeur sur true pour appliquer la stratégie.Définissez la valeur sur |
vrai | Facultatif |
| async | Cet attribut est obsolète. | faux | Obsolète |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
À utiliser, en plus de l'attribut, pour appliquer un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur d'Apigee 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, également appelé paramètre.
- 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. Par exemple, vous pouvez utiliser cet élément de configuration pour produire un en-tête JWS qui, une fois décodé, ressemble à ceci :
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}Cet en-tête JWS déclare que le paramètre d'en-tête hyb est important et que tout destinataire du JWS doit comprendre la signification et la valeur de ce paramètre.
Conformément à la norme IETF RFC 7515, le destinataire d'un JWS doit rejeter le JWS comme non valide si celui-ci ne comprend pas un ou plusieurs des paramètres référencés dans le paramètre crit. Dans Apigee, la règle VerifyJWS est conforme à ce comportement.
Pour chaque paramètre répertorié dans le paramètre crit, il vérifie que l'élément <KnownHeaders> de la règle VerifyJWS répertorie également ce paramètre.
Tout en-tête identifié par la règle VerifyJWS dans crit et qui ne figure pas encore dans le fichier <KnownHeaders> entraîne le rejet de la règle VerifyJWS.
| Par défaut | N/A |
| Présence | Facultatif |
| Type | Tableau d'une ou de plusieurs chaînes séparées par une virgule |
| Valeurs valides | Tableau ou référence à 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 un JWS avec une charge utile dissociée, le JWS généré omet la charge utile et se présente sous la forme suivante :
[header]..[signature]
Avec un JWS utilisant une charge utile dissociée, il vous incombe de transmettre la charge utile non codée d'origine à la partie de validation, avec le JWS sérialisé.
| Par défaut | faux |
| 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 | faux |
| Présence | Facultatif |
| Type | Booléen |
| Valeurs valides | true ou false |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
Spécifie le nom de la variable de contexte que la règle définira avec le JWS généré.
Par défaut, la règle place le JWS dans la variable de contexte nommée 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 |
| Valeurs valides | Modèle de message ou référence à une variable contenant la charge utile. |
Élément <PrivateKey>
Cet élément est facultatif et ne doit être utilisé que lorsque <Algorithm> est l'une des options RS*, PS* ou ES*. Il spécifie la clé privée à utiliser pour la signature, ainsi que d'autres informations sur la clé privée. Il est utilisé lorsque l'algorithme est un algorithme asymétrique.
<PrivateKey> <Value ref="private.privatekey"</Value> </PrivateKey>
| Valeur par défaut : | N/A |
| Présence : | Facultatif. Toutefois, vous devez inclure exactement l'un des éléments <PrivateKey> ou <SecretKey>.
Utilisez l'élément <PrivateKey> lorsque l'algorithme est RS*, PS* ou ES*, et utilisez l'élément <SecretKey> lorsque l'algorithme est HS*.
|
| Type : | N/A |
<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.
| 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.
| 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 avec l'attribut ref. Apigee rejettera la configuration d'une stratégie non valide dans laquelle le mot de passe est spécifié en texte brut. La variable de flux doit comporter le préfixe "private". Par exemple, |
<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.
| Par défaut | N/A |
| Présence | Obligatoire lorsque vous utilisez la règle pour générer un JWS avec l'un des algorithmes RS*, PS* ou ES*. |
| 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, |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
Spécifie la clé secrète à utiliser lors de la génération d'un jeton JWS qui utilise un algorithme symétrique (HS*), choisie parmi HS256, HS384 ou HS512.
Cet élément est facultatif. Toutefois, vous devez inclure exactement l'un des éléments <PrivateKey> ou <SecretKey>.
Utilisez l'élément <PrivateKey> lors de la génération d'un jeton JWS signé avec un algorithme asymétrique (RS*, PS* ou ES*), et utilisez l'élément <SecretKey> lors de la génération d'un jeton JWS signé avec un algorithme symétrique (algorithme tel que HS*).
Enfants de <SecretKey>
Le tableau suivant fournit une description des éléments enfants et des attributs de :
<SecretKey>
| Enfant | Présence | Description |
|---|---|---|
| codage (attribut) | Facultatif | Spécifie le mode d'encodage de la clé dans la variable référencée. Par défaut, lorsqu'aucun attribut <SecretKey encoding="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> Dans l'exemple ci-dessus, l'encodage étant |
| ID (élément) | Facultatif | Identifiant de clé. La valeur peut être n'importe quelle chaîne. Vous pouvez spécifier la valeur sous forme de valeur texte littérale, ou indirectement, via une référence de variable, avec l'attribut <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> La règle inclut cet identifiant de clé en tant que revendication |
| Valeur (élément) | Requis | Clé secrète encodée. Spécifie la clé secrète utilisée pour signer la charge utile.
Utilisez l'attribut <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee applique un niveau de sécurité de clé minimal 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. |
<Type>
<Type>type-string-here</Type>
Élément facultatif dont la seule valeur autorisée est Signed, indiquant que la règle génère un jeton JWS signé. <Type> est fourni uniquement pour correspondre à l'élément correspondant des règles GenerateJWT et VerifyJWT (réègles avec lesquelles les valeurs autorisées sont Signed ou Encrypted).
| Par défaut | N/A |
| Présence | Facultatif |
| Type | Chaîne |
| Valeur valide | Signed |
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 et les variables d'erreur définies par Apigee lorsque cette règle 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 problème de revendication ou de revendication manquante, de problème d'en-tête ou d'en-tête 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 fichier JWS possède une charge utile de contenu dissociée. |
steps.jws.KeyIdMissing |
401 |
La règle de vérification utilise un JWKS en tant que source pour les clés publiques, mais le jeton JWS signé n'inclut pas la 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 |
Se 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 : RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512. |
|
|
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 | Lieu | 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 exceptions, la meilleure 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>