--- 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: 7.2 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-02T16:30:54Z 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](RequestsResponsesContexts.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 information taken from the request or associated contexts in IG. If this property is a map, the structure must have the format `Map`, and map values are evaluated as runtime expressions. For example, ```json "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](preface.html#definition-map), `Map`. For example, ```json "template": "${contexts.attributes}" ``` See also [Expressions](Expressions.html#Expressions). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The SecretsProvider object to query for JWT signing or encryption keys. For more information, see [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, see [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 [Deprecation](../release-notes/deprecated-functionality.html). | 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, "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. * `"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, see [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). * `"algorithm"`: *configuration expression<[string](preface.html#definition-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](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, see [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 [Deprecation](../release-notes/deprecated-functionality.html). | 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 [Deprecation](../release-notes/deprecated-functionality.html). | 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 [Deprecation](../release-notes/deprecated-functionality.html). | 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 [Deprecation](../release-notes/deprecated-functionality.html). | 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). * `"algorithm"`: *configuration expression<[string](preface.html#definition-string)>, required* The algorithm used to encrypt the JWT. For information about available algorithms, see [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, see [RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). ## Examples For examples, see [Pass runtime data downstream in a JWT](../gateway-guide/runtime.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)