Identity Gateway 2023.11

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 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 with the format 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, as follows:

{
  "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 reference, optional

The SecretsProvider object to query for JWT signing or encryption keys. For more information, refer to SecretsProvider.

Default: The route’s default secret service. For more information, refer to Default secrets object.

"signature": object, optional
The use of unsigned or unencrypted JWTs is deprecated and not considered secure. For more information, refer to the Deprecated section of the Release Notes.

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>,
    "includeKeyId": 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.

This secret ID must point to a CryptoKey.

"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 IG:

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

This secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, required

The algorithm used to encrypt the JWT signature.

For information about available algorithms, refer to 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, refer to 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 the Deprecated section of the Release Notes.

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 the Deprecated section of the Release Notes.

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 the Deprecated section of the Release Notes.

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 the Deprecated section of the Release Notes.

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.

This secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, required

The algorithm used to encrypt the JWT.

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

Examples

For examples, refer to Passing data along the chain

More information

org.forgerock.openig.filter.JwtBuilderFilter

org.forgerock.openig.filter.JwtBuilderContext