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, or a signed then encrypted JWT:

  • 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
  }
}

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

A JWT signature to allow the authenticity of the claims/data to be validated. A signed JWT can be encrypted.

{
  "signature": {
    "secretId":  configuration expression<secret-id>,
    "algorithm": configuration expression<string>,
    "encryption": object
  }
}
"secretId": configuration expression<secret-id>, required if signature is used

The secret ID of the key used to sign the JWT.

"algorithm": expression<string>, optional

The algorithm with which to sign the JWT.

The following algorithms are supported but not necessarily tested in IG:

Default: RS256

"encryption": object, optional

Encrypt the JWT.

{
  "encryption": {
    "secretId": configuration expression<secret-id>,
    "algorithm": configuration expression<string>,
    "method": configuration expression<enumeration>
  }
}
"secretId": configuration expression<secret-id>, optional

The secret ID of the key used to encrypt the JWT. The value is mapped to key aliases in KeyStoreSecretStore.

For information about supported formats for secret-id, see secret-id.

"algorithm": expression<string>, required

The algorithm used to encrypt the JWT.

For information about available algorithms, see "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 "enc" (Encryption Algorithm) Header Parameter Values for JWE .