PingGateway 2024.9

JwtValidationFilter

Validates an unsigned, signed, encrypted, or signed and encrypted JWT. The order of signing and encryption isn’t 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 and 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.

Usage

{
  "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
  }
}
json

Properties

"jwt": runtime expression<string>, required

The value of the JWT in the request. Cannot be null.

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

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

For information about how signatures are validated, refer to Validate the signature of signed tokens. For information about how each type of secret store resolves named secrets, refer to Secrets.

"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.

For information about how each type of secret store resolves named secrets, see Secrets.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for passwords and cryptographic keys.

"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 following items:

The following examples provide checks:

Check that 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))"
    ]
  }
}
json
Check that the value of the claim sub is george
"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "builder.claim('subname', JsonValue::asString, isEqualTo('george'))"
    ]
  }
}
json
Check that the value of the custom sub-claim is ForgeRock
"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "builder.claim('customclaim/subclaim', JsonValue::asString, isEqualTo('ForgeRock'));"
    ]
  }
}
json
Check the value 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('ForgeRock AM'));"
    ]
  }
}
json
Check that 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()))" ]
  }
}
json
Check that 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())));"
    ]
  }
}
json
Check that 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)/))" ]
  }
}
json

Default: Claims aren’t validated

"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 skew allowance is by default zero.

"failureHandler": Handler 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.

Default: HTTP 403 Forbidden, the request stops being executed.

Example

For an example of using JwtValidationFilter, refer to JWT validation.

More information

org.forgerock.openig.filter.jwt.JwtValidationFilter

org.forgerock.openig.filter.jwt.JwtValidationContext

org.forgerock.openig.filter.jwt.JwtValidationErrorContext

OpenID Connect Core 1.0 incorporating errata set 1