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 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": {
"secretId": configuration expression<secret-id>,
"includeKeyId": configuration expression<secret-id>,
"algorithm": configuration expression<string>,
"encryption": {
"secretId": configuration expression<secret-id>,
"algorithm": configuration expression<string>,
"method": configuration expression<string>
}
},
"encryption": {
"secretId": secret-id,
"algorithm": configuration expression<string>,
"method": configuration expression<enumeration>
}
}
}Properties
template
"template": map or runtime expression<map>, required
A map of one or more data pairs with the format Map<String, Object>, where:
-
The key is the name of a data field
-
The value is a data object, or a runtime expression that evaluates to a data object
The following formats are allowed:
{
"template": {
"string": "runtime expression<object>",
...
}
}{
"template": "runtime expression<map>"
}In the following example, the property is a map whose values are runtime expressions that evaluate to objects in the context:
{
"template": {
"name": "${contexts.userProfile.commonName}",
"email": "${contexts.userProfile.rawInfo.mail[0]}",
"address": "${contexts.userProfile.rawInfo.postalAddress[0]}",
"phone": "${contexts.userProfile.rawInfo.telephoneNumber[0]}"
}
}In the following example, the property is a runtime expression that evaluates to a Map<String, Object>:
{
"template": "${contexts.attributes}"
}Use the now dynamic binding
to dynamically set the value of an attribute that represents time.
For example, set the value of attributes to a defined time after the expressions are evaluated:
{
"name": "JwtBuilderFilter-1",
"type": "JwtBuilderFilter",
"config": {
"template": {
"iat": "${now.epochSeconds}",
"nbf": "${now.plusSeconds(10).epochSeconds}",
"exp": "${now.plusSeconds(20).epochSeconds}"
},
"secretsProvider": "FileSystemSecretStore-1",
"signature": {
"secretId": "id.key.for.signing.jwt",
"algorithm": "RS512"
}
}
}secretsProvider
"secretsProvider": SecretsProvider reference, required
The SecretsProvider to query for JWT signing or encryption keys.
signature
"signature": object, "signature" and/or "encryption" is required
A JWT signature to allow the authenticity of the claims/data to be validated. A signed JWT can be encrypted.
The encryption settings take precedence over this property.
"includeKeyId": configuration expression<boolean>, optional-
When
true, include the ID of the signature key in the JWT header.Default:
true
"algorithm": configuration expression<string>, optional-
The algorithm to sign the JWT.
The following algorithms are supported but not necessarily tested in PingGateway:
-
Algorithms described in RFC 7518: Cryptographic Algorithms for Digital Signatures and MACs.
For RSASSA-PSS, you must install Bouncy Castle. Learn more from The Legion of the Bouncy Castle.
-
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.
"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.This secret ID must point to a CryptoKey.
"algorithm": configuration expression<string>, required-
The algorithm used to encrypt the JWT signature.
Learn about available algorithms in RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.
"method": configuration expression<string>, required-
The method used to encrypt the JWT signature.
Learn about available methods in RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.
encryption
"encryption": object, "signature" and/or "encryption" is required
Configuration to encrypt the JWT.
This property takes precedence over the signature settings.
"secretId": secret-id, optional-
The secret ID of the key used to encrypt the JWT. The value is mapped to key
aliasesin KeyStoreSecretStore.This secret ID must point to a CryptoKey.
"algorithm": configuration expression<string>, required-
The algorithm used to encrypt the JWT.
Learn about available algorithms in RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.
"method": configuration expression<enumeration>, required-
The method used to encrypt the JWT.
Learn about available methods in RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.
Examples
You can find examples in Pass data along the chain