---
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: 2023.11
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-03T11:21:31Z
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](Contexts.html#JwtValidationContext).

If the JWT is not validated, data is provided in the [JwtValidationErrorContext](Contexts.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<string>,
    "verificationSecretId": configuration expression<secret-id>,
    "decryptionSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "skewAllowance": configuration expression<duration>,
    "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.

  This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types).

  If configured, the token must be signed. If not configured, IG does not verify the signature.

  For information about how signatures are validated, refer to [Validate the signature of signed tokens](../security-guide/keys.html#secret-valid-signature). For information about how each type of secret store resolves named secrets, refer to [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.

  This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types).

  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<JsonValue, java.time.LocalDate, Exception> 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, refer to [JWT validation](../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)