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.
If the JWT isn’t validated, data is provided in the JwtValidationErrorContext.

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.

Usage

{
   "name": string,
   "type": "IdTokenValidationFilter",
   "config": {
     "idToken": runtime expression<string>,
     "audience": configuration expression<string>,
     "issuer": configuration 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

idToken

"idToken": runtime expression<string>, required

The ID token as an expression representing the JWT or signed JWT in the request. Cannot be null.

audience

"audience": configuration expression<string>, required

One aud claim to check on the JWT. Cannot be null.

issuer

"issuer": configuration expression<string>, optional

One iss claim to check on the JWT. Can be null.

verificationSecretId

"verificationSecretId": configuration expression<secret-id>, required to verify the signature of signed tokens

The secret ID used for the secret to verify the signature of signed tokens.

This secret ID must point to a CryptoKey.

If configured, the token must be signed. If not configured, PingGateway doesn’t verify the signature.

Learn more in Validate the signature of signed tokens.

Learn how each type of secret store resolves named secrets in Secrets.

decryptionSecretId

"decryptionSecretId": configuration expression<secret-id>, 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.

If configured, the token must be encrypted. If not configured, PingGateway doesn’t verify the encryption.

Learn how each type of secret store resolves named secrets in Secrets.

secretsProvider

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for passwords and cryptographic keys.

skewAllowance

"skewAllowance": configuration expression<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 default skew allowance is zero.

customizer

"customizer": JwtValidatorCustomizer 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 builder object in Available Objects.
Transformer methods to enrich the builder object in org.forgerock.openig.util.JsonValues.
Constraints in org.forgerock.openig.tools.jwt.validation.Constraints.
Other properties for ScriptableJwtValidatorCustomizer in PingGateway scripts.

The following examples verify claims:

Check the value of the claim greaterThan5 is greater than 5

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "builder.claim('/greaterThan5', JsonValue::asInteger, isGreaterThan(5))"
    ]
  }
}

Check the value of the claim sub is george

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "builder.claim('subname', JsonValue::asString, isEqualTo('george'))"
    ]
  }
}

Check the value of the custom sub-claim is Ping Identity

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "builder.claim('customclaim/subclaim', JsonValue::asString, isEqualTo('Ping Identity'));"
    ]
  }
}

Check the values of multiple claims

"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 the value of val1 is greater than val2

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [ "builder.claim('/val1', JsonValue::asInteger, isGreaterThan(claim('/val2').asInteger()))" ]
  }
}

Check the value of val1 is greater than val2, when both are YYYY-MM-DD dates

"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 the claim issuer matches the regex pattern

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [ "builder.claim('iss', JsonValue::asString, find(~/.*am\.example\.(com|org)/))" ]
  }
}

Default: Claims aren’t validated