JwtBuilderFilter
Collects data at runtime, packs it in a JSON Web Token (JWT), and places the resulting JWT into the JwtBuilderContext.
Configure JwtBuilderFilter to create an unsigned JWT, a signed JWT, a signed then encrypted JWT, or an encrypted JTW:
-
Sign the JWT so that an application can validate the authenticity of the claims/data. The JWT can be signed with a shared secret or private key, and verified with a shared secret or corresponding public key.
-
Encrypt the JWT to reduce the risk of a data breach.
For a flexible way to pass identity or other runtime information to the protected application, use this filter with a HeaderFilter.
To enable downstream filters and handlers to verify signed and/or encrypted JWTs built by this filter, use this filter with a JwkSetHandler.
Usage
{
"name": string,
"type": "JwtBuilderFilter",
"config": {
"template": map or runtime expression<map>,
"secretsProvider": SecretsProvider reference,
"signature": object,
"encryption": object
}
}Properties
"template": map or runtime expression<map>, required-
A map of information taken from the request or associated contexts in IG.
If this property is a map, the structure must have the format
Map<String, Object>, and map values are evaluated as runtime expressions. For example,"template": { "name": "${contexts.userProfile.commonName}", "email": "${contexts.userProfile.rawInfo.mail[0]}", "address": "${contexts.userProfile.rawInfo.postalAddress[0]}", "phone": "${contexts.userProfile.rawInfo.telephoneNumber[0]}" }If this property is an expression, its evaluation must give an object of type map,
Map<String, Object>. For example,"template": "${contexts.attributes}"See also Expressions.
"secretsProvider": SecretsProvider reference, optional-
The SecretsProvider object to query for JWT signing or encryption keys. For more information, see SecretsProvider.
Default: The route’s default secret service. For more information, see Default secrets object.
"signature": object, optional-
The use of unsigned or unencrypted JWTs is deprecated and not considered secure. For more information, refer to Deprecation. A JWT signature to allow the authenticity of the claims/data to be validated. A signed JWT can be encrypted.
JwtBuilderFilter.encryptiontakes precedence over this property.{ "signature": { "secretId": configuration expression<secret-id>, "algorithm": configuration expression<string>, "encryption": object, "keystore": KeyStore reference, //deprecated "alias": configuration expression<string>, //deprecated "password": configuration expression<string> //deprecated } }"secretId": configuration expression<secret-id>, required ifsignatureis used-
The secret ID of the key to sign the JWT.
"algorithm": configuration expression<string>, optional-
The algorithm to sign the JWT.
The following algorithms are supported but not necessarily tested in IG:
-
Algorithms described in RFC 7518: Cryptographic Algorithms for Digital Signatures and MACs.
For RSASSA-PSS, you must install Bouncy Castle. For information, see The Legion of the Bouncy Castle.
-
From IG 6.1,
Ed25519described in CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE).Default: RS256
-
"encryption": object, optional-
Configuration to encrypt the JWT signature.
{ "encryption": { "secretId": configuration expression<secret-id>, "algorithm": configuration expression<string>, "method": configuration expression<string> } }"secretId": configuration expression<secret-id>, optional-
The secret ID of the key used to encrypt the JWT signature. The value is mapped to key
aliasesin KeyStoreSecretStore. "algorithm": configuration expression<string>, required-
The algorithm used to encrypt the JWT signature.
For information about available algorithms, see RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.
"method": configuration expression<string>, required-
The method used to encrypt the JWT signature.
For information about available methods, see RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.
"keystore": KeyStore reference, optional-
This property is deprecated; use the signaturesubpropertysecretIdinstead. For more information, refer to Deprecation.The Java KeyStore containing the key used to sign the JWT.
The name of a KeyStore object defined in the heap, or an inline KeyStore configuration object.
"alias": configuration expression<string>, required ifsignatureis used-
This property is deprecated; use the signaturesubpropertysecretIdinstead. For more information, refer to Deprecation.Alias for the key.
Note Because KeyStore converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.
"password": expression<string>, required ifsignatureis used-
This property is deprecated; use the signaturesubpropertysecretIdinstead. For more information, refer to Deprecation.Password for the key.
"encryption": object, optional-
The use of unsigned or unencrypted JWTs is deprecated and not considered secure. For more information, refer to Deprecation. Configuration to encrypt the JWT. This property take precedence over
JwtBuilderFilter.signature.{ "encryption": { "secretId": secret-id, "algorithm": configuration expression<string>, "method": configuration expression<enumeration> } }"secretId": secret-id, optional-
The secret ID of the key used to encrypt the JWT. The value is mapped to key
aliasesin KeyStoreSecretStore. "algorithm": configuration expression<string>, required-
The algorithm used to encrypt the JWT.
For information about available algorithms, see RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.
"method": configuration expression<enumeration>, required-
The method used to encrypt the JWT.
For information about available methods, see RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.
Examples
For examples, see Pass runtime data downstream in a JWT