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.encryption takes 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 if signature is 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, Ed25519 described 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 aliases in 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 signature subproperty secretId instead. 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 if signature is used

This property is deprecated; use the signature subproperty secretId instead. 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 if signature is used

This property is deprecated; use the signature subproperty secretId instead. 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 aliases in 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

More information

org.forgerock.openig.filter.JwtBuilderFilter

org.forgerock.openig.filter.JwtBuilderContext

Identity Gateway 7.2

JwtBuilderFilter

Usage

Properties

Examples

More information