--- title: JwtValidationFilter description: Validates an unsigned, signed, encrypted, or signed and encrypted JWT. The order of signing and encryption is not important; a JWT can be signed and then encrypted, or encrypted and then signed. component: pinggateway version: 7.2 page_id: pinggateway:reference:JwtValidationFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/JwtValidationFilter.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/JwtValidationFilter.html section_ids: JwtValidationFilter-usage: Usage JwtValidationFilter-properties: Properties JwtValidationFilter-example: Example JwtValidationFilter-moreinfo: More information --- # JwtValidationFilter Validates an unsigned, signed, encrypted, or signed and encrypted JWT. The order of signing and encryption is not important; a JWT can be signed and then encrypted, or encrypted and then signed. If the JWT is validated, the request continues down the chain. The data is provided in the [JwtValidationContext](RequestsResponsesContexts.html#JwtValidationContext). If the JWT is not validated, data is provided in the [JwtValidationErrorContext](RequestsResponsesContexts.html#JwtValidationErrorContext). If a failure handler is configured, the request passes to the failure handler. Otherwise, an HTTP 403 Forbidden is returned. ## Usage ```json { "name": string, "type": "JwtValidationFilter", "config": { "jwt": runtime expression, "verificationSecretId": configuration expression, "decryptionSecretId": configuration expression, "secretsProvider": SecretsProvider reference, "skewAllowance": configuration expression, "customizer": JwtValidatorCustomizer reference, "failureHandler": Handler reference } } ``` ## Properties * `"jwt"`: *runtime expression<[string](preface.html#definition-string)>, required* The value of the JWT in the request. Cannot be null. - `"verificationSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required to verify the signature of signed tokens* The secret ID for the secret to verify the signature of signed tokens. If configured, the token must be signed. If not configured, IG does not verify the signature. For information about how signatures are validated, see [Validating the signature of signed tokens](../gateway-guide/about.html#secret-valid-signature). For information about how each type of secret store resolves named secrets, see [Secrets](secrets.html). - `"decryptionSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required if AM secures access tokens with encryption* The secret ID for the secret to verify the encryption of tokens. If configured, the token must be encrypted. If not configured, IG does not verify the encryption. For information about how each type of secret store resolves named secrets, see [Secrets](secrets.html). - `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](secrets.html#SecretsProvider) to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline. * `"customizer"`: *JwtValidatorCustomizer [reference](preface.html#definition-reference), optional* A set of validation constraints for JWT claims and sub-claims. If a claim is not validated against the constraint, the JWT is not validated. The customizer does not override existing constraints, such as `aud`, `iss`, `exp`, and `iat`, which are predefined in the IdTokenValidationFilter, Defining a new constraint on an already constrained claim has an impact only if the new constraint is more restrictive. JwtValidatorCustomizer provides a ScriptableJwtValidatorCustomizer to enrich a `builder` object by using its methods. Get more information about the following items: * The `builder` object, at [Available Objects](Scripts.html#Scripts-availableob). * Transformer methods, to enrich the builder object, at [org.forgerock.openig.util.JsonValues](../_attachments/apidocs/org/forgerock/openig/util/JsonValues.html). * Constraints, at [org.forgerock.openig.tools.jwt.validation.Constraints](../_attachments/apidocs/org/forgerock/openig/tools/jwt/validation/Constraints.html). * Other properties for ScriptableJwtValidatorCustomizer, at [Scripts](Scripts.html). The following examples provide checks: * Check that the value of the claim `greaterThan5` is greater than 5 ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('/greaterThan5', JsonValue::asInteger, isGreaterThan(5))" ] } } ``` * Check that the value of the claim `sub` is `george` ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('subname', JsonValue::asString, isEqualTo('george'))" ] } } ``` * Check that the value of the custom sub-claim is `ForgeRock` ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('customclaim/subclaim', JsonValue::asString, isEqualTo('ForgeRock'));" ] } } ``` * Check the value of multiple claims ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('aud', listOf(JsonValue::asString), contains('My App'))", " .claim('iat', instant(), isInThePast())", " .claim('exp', instant(), isInTheFuture());", "builder.claim('iss', JsonValue::asString, isEqualTo('ForgeRock AM'));" ] } } ``` * Check that the value of `val1` is greater than `val2` ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('/val1', JsonValue::asInteger, isGreaterThan(claim('/val2').asInteger()))" ] } } ``` * Check that the value of `val1` is greater than `val2`, when both are YYYY-MM-DD dates ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "Function asDate() {", " return (jsonValue) -> java.time.LocalDate.parse(jsonValue.asString());", "}", "builder.claim('claim1', asDate(), isGreaterThan(claim('claim2').as(asDate())));" ] } } ``` * Check that the claim issuer matches the regex pattern ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('iss', JsonValue::asString, find(~/.*am\.example\.(com|org)/))" ] } } ``` Default: Claims are not validated * `"skewAllowance"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The duration to add to the validity period of a JWT to allow for clock skew between different servers. To support a zero-trust policy, the skew allowance is by default zero. A `skewAllowance` of 2 minutes affects the validity period as follows: * A JWT with an `iat` of 12:00 is valid from 11:58 on the IG clock. * A JWT with an `exp` 13:00 is expired after 13:02 on the IG clock. Default: `zero` * `"failureHandler"`: *Handler [reference](preface.html#definition-reference), optional* Handler to treat the request on failure. Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also [Handlers](Handlers.html). Default: HTTP 403 Forbidden, the request stops being executed. ## Example For an example of using JwtValidationFilter, see [Validate JWTs](../gateway-guide/validate-jwt.html). ## More information [org.forgerock.openig.filter.jwt.JwtValidationFilter](../_attachments/apidocs/org/forgerock/openig/filter/jwt/JwtValidationFilter.html) [org.forgerock.openig.filter.jwt.JwtValidationContext](../_attachments/apidocs/org/forgerock/openig/filter/jwt/JwtValidationContext.html) [org.forgerock.openig.filter.jwt.JwtValidationErrorContext](../_attachments/apidocs/org/forgerock/openig/filter/jwt/JwtValidationErrorContext.html) [OpenID Connect Core 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-core-1_0.html)