--- title: JwtBuilderFilter description: Collects data at runtime, packs it in a JSON Web Token (JWT), and places the resulting JWT into the JwtBuilderContext. component: pinggateway version: 2023.11 page_id: pinggateway:reference:JwtBuilderFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/JwtBuilderFilter.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-03T11:21:31Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/JwtBuilderFilter.html section_ids: JwtBuilderFilter-usage: Usage JwtBuilderFilter-properties: Properties JwtBuilderFilter-example: Examples JwtBuilderFilter-moreinfo: More information --- # JwtBuilderFilter Collects data at runtime, packs it in a JSON Web Token (JWT), and places the resulting JWT into the [JwtBuilderContext](Contexts.html#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](Filters.html#HeaderFilter). To enable downstream filters and handlers to verify signed and/or encrypted JWTs built by this filter, use this filter with a [JwkSetHandler](Handlers.html#JwkSetHandler). ## Usage ```json { "name": string, "type": "JwtBuilderFilter", "config": { "template": map or runtime expression, "secretsProvider": SecretsProvider reference, "signature": object, "encryption": object } } ``` ## Properties * `"template"`: *[map](preface.html#definition-map) or runtime expression\, required* A map of one or more data pairs with the format `Map`, 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: ```json { "template": { "string": "runtime expression", ... } } ``` ```json { "template": "runtime expression" } ``` In the following example, the property is a map whose values are runtime [expressions](Expressions.html#Expressions) that evaluate to objects in the context: ```json { "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](Expressions.html#Expressions) that evaluates to a map with the format `Map`: ```json { "template": "${contexts.attributes}" } ``` Use the `now` [dynamic binding](Expressions.html#expressions-dynamic-bindings) 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: ```json { "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](preface.html#definition-reference), optional* The SecretsProvider object to query for JWT signing or encryption keys. For more information, refer to [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, refer to [Default secrets object](secrets.html#default-secrets-object). * `"signature"`: *[object](preface.html#definition-object), optional* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of unsigned or unencrypted JWTs is deprecated and not considered secure. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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. ```json { "signature": { "secretId": configuration expression, "includeKeyId": configuration expression "algorithm": configuration expression, "encryption": object, "keystore": Keystore reference, //deprecated "alias": configuration expression, //deprecated "password": configuration expression //deprecated } } ``` * `"secretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required if `signature` is used* The secret ID of the key to sign the JWT. This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"includeKeyId"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* When `true`, include the ID of the signature key in the JWT header. Default: `true` * `"algorithm"`: *configuration expression<[string](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc7518#section-3). For RSASSA-PSS, you must install Bouncy Castle. For information, refer to [The Legion of the Bouncy Castle](https://www.bouncycastle.org). * From IG 6.1, `Ed25519` described in [CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)](https://www.rfc-editor.org/rfc/rfc8037). Default: RS256 * `"encryption"`: *[object](preface.html#definition-object), optional* Configuration to encrypt the JWT signature. ```json { "encryption": { "secretId": configuration expression, "algorithm": configuration expression, "method": configuration expression } } ``` * `"secretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID of the key used to encrypt the JWT signature. The value is mapped to key `aliases` in [KeyStoreSecretStore](secrets.html#KeyStoreSecretStore). This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"algorithm"`: *configuration expression<[string](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc7518#section-4.1). * `"method"`: *configuration expression<[string](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). * `"keystore"`: *KeyStore reference, optional* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use the `signature` subproperty `secretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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\, required if `signature` is used* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use the `signature` subproperty `secretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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\, required if `signature` is used* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use the `signature` subproperty `secretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | Password for the key. * `"encryption"`: *[object](preface.html#definition-object), optional* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of unsigned or unencrypted JWTs is deprecated and not considered secure. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | Configuration to encrypt the JWT. This property take precedence over `JwtBuilderFilter.signature`. ```json { "encryption": { "secretId": secret-id, "algorithm": configuration expression, "method": configuration expression } } ``` * `"secretId"`: *[secret-id](preface.html#definition-secretid), optional* The secret ID of the key used to encrypt the JWT. The value is mapped to key `aliases` in [KeyStoreSecretStore](secrets.html#KeyStoreSecretStore). This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"algorithm"`: *configuration expression<[string](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc7518#section-4.1). * `"method"`: *configuration expression<[enumeration](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). ## Examples For examples, refer to [Passing data along the chain](../gateway-guide/data-downstream.html) ## More information [org.forgerock.openig.filter.JwtBuilderFilter](../_attachments/apidocs/org/forgerock/openig/filter/JwtBuilderFilter.html) [org.forgerock.openig.filter.JwtBuilderContext](../_attachments/apidocs/org/forgerock/openig/filter/JwtBuilderContext.html)