--- 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: 2026 page_id: pinggateway:reference:JwtBuilderFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/JwtBuilderFilter.html revdate: 2025-06-02T18:01:47Z section_ids: JwtBuilderFilter-usage: Usage JwtBuilderFilter-properties: Properties JwtBuilderFilter-template: template JwtBuilderFilter-secretsProvider: secretsProvider JwtBuilderFilter-signature: signature JwtBuilderFilter-encryption: encryption 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](JwtBuilderContext.html). Configure JwtBuilderFilter to create 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](HeaderFilter.html). To enable downstream filters and handlers to verify signed and/or encrypted JWTs built by this filter, use this filter with a [JwkSetHandler](JwkSetHandler.html). ## Usage ```none { "name": string, "type": "JwtBuilderFilter", "config": { "template": map or runtime expression, "secretsProvider": SecretsProvider reference, "signature": { "secretId": configuration expression, "includeKeyId": configuration expression, "algorithm": configuration expression, "encryption": { "secretId": configuration expression, "algorithm": configuration expression, "method": configuration expression } }, "encryption": { "secretId": secret-id, "algorithm": configuration expression, "method": configuration expression } } } ``` ## Properties ### template `"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: ```none { "template": { "string": "runtime expression", ... } } ``` ```none { "template": "runtime expression" } ``` In the following example, the property is a map whose values are runtime [expressions](Expressions.html) 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 that evaluates to a `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: ```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"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](SecretsProvider.html) to query for JWT signing or encryption keys. ### signature `"signature"`: *[object](preface.html#definition-object), "signature" and/or "encryption" is required* A JWT signature to allow the authenticity of the claims/data to be validated. A signed JWT can be encrypted. The [encryption](#JwtBuilderFilter-encryption) settings take precedence over this property. * `"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 PingGateway: * 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. Learn more from [The Legion of the Bouncy Castle](https://www.bouncycastle.org). * `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. * `"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](KeyStoreSecretStore.html). 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. Learn about available algorithms in [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. Learn about available methods in [RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). ### encryption `"encryption"`: *[object](preface.html#definition-object), "signature" and/or "encryption" is required* Configuration to encrypt the JWT. This property takes precedence over the [signature](#JwtBuilderFilter-signature) settings. * `"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](KeyStoreSecretStore.html). 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. Learn about available algorithms in [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. Learn about available methods in [RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). ## Examples You can find examples in [Passing PingAM 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)