--- title: IdTokenValidationFilter description: Validates an ID token by checking the standard claims, aud, exp, and iat. If specified in the configuration, this filter also checks the ID token issuer and signature. component: pinggateway version: 2025.9 page_id: pinggateway:reference:IdTokenValidationFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/IdTokenValidationFilter.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/IdTokenValidationFilter.html section_ids: IdTokenValidationFilter-usage: Usage IdTokenValidationFilter-properties: Properties IdTokenValidationFilter-example: Example IdTokenValidationFilter-moreinfo: More information --- # IdTokenValidationFilter Validates an ID token by checking the standard claims, `aud`, `exp`, and `iat`. If specified in the configuration, this filter also checks the ID token issuer and signature. This filter passes data into the context as follows: * If the JWT is validated, the request continues down the chain. The data is provided in the [JwtValidationContext](JwtValidationContext.html). * If the JWT isn't validated, data is provided in the [JwtValidationErrorContext](JwtValidationErrorContext.html). If a failure handler is configured, the request passes to the failure handler. Otherwise, an HTTP 403 Forbidden is returned. The `iat` claim is required, and the `iat` minus the `skewAllowance` must be before the current time on the PingGateway clock. For information, see [OpenID Connect Core 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-core-1_0.html). ## Usage ```json { "name": string, "type": "IdTokenValidationFilter", "config": { "idToken": runtime expression, "audience": configuration expression, "issuer": configuration expression, "skewAllowance": configuration expression, "verificationSecretId": configuration expression, "secretsProvider": SecretsProvider reference, "customizer": JwtValidatorCustomizer reference, "failureHandler": Handler reference } } ``` ## Properties * `"idToken"`: *runtime expression<[string](preface.html#definition-string)>, required* The ID token as an expression representing the JWT or signed JWT in the request. Cannot be null. * `"audience"`: *configuration expression<[string](preface.html#definition-string)>, required* One `aud` claim to check on the JWT. Cannot be null. * `"issuer"`: *configuration expression<[string](preface.html#definition-string)>, optional* One `iss` claim to check on the JWT. Can be null. - `"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. 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 PingGateway clock. * A JWT with an `exp` 13:00 is expired after 13:02 on the PingGateway clock. Default: To support a zero-trust policy, the skew allowance is by default `zero`. * `"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, PingGateway doesn't 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). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](SecretsProvider.html) to query for passwords and cryptographic keys. - `"customizer"`: *JwtValidatorCustomizer [reference](preface.html#definition-reference), optional* A set of validation constraints for JWT claims and sub-claims. These constraints are in addition to internally-defined constraints, such as `aud`, `iss`, `exp`, and `iat`. If a claim isn't validated against a constraint, the JWT isn't validated. The customizer doesn't override existing constraints. 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 [PingGateway 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 `test` ```json "customizer": { "type": "ScriptableJwtValidatorCustomizer", "config": { "type": "application/x-groovy", "source": [ "builder.claim('customclaim/subclaim', JsonValue::asString, isEqualTo('test'));" ] } } ``` * 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('PingAM'));" ] } } ``` * 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 aren't validated * `"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 [PingGateway handlers](Handlers.html). Default: HTTP 403 Forbidden, the request stops being executed. ## Example Find an example of how the IdTokenValidationFilter is used in [ID token validation with PingAM](../gateway-guide/validate-idtoken.html). ## More information [org.forgerock.openig.filter.oauth2.client.IdTokenValidationFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/IdTokenValidationFilterHeaplet.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)