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.

If the JWT is not 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
  }
}

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.

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. For information about how each type of secret store resolves named secrets, see 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.

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.
"secretsProvider": SecretsProvider reference, required to verify the signature of signed JWTs: The 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, optional

Defines 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.
Transformer methods, to enrich the builder object, at org.forgerock.openig.util.JsonValues.
Constraints, at org.forgerock.openig.tools.jwt.Constraints.
Other properties for ScriptableJwtValidatorCustomizer, at Scripts.

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))"
    ]
  }
}

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'))"
    ]
  }
}

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'));"
    ]
  }
}

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'));"
    ]
  }
}

Check that the value of /val1 is greater than the value of /val2

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

Check that the claim issuer matches the regex pattern

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

Default: Claims are not 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. 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, 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

Validate an Unsigned, Unencrypted JWT

Set up AM as described in Validate Access_Tokens Through the Introspection Endpoint, and add the additional scope openid to the OAuth 2.0 Client.

In a terminal window, use a curl command similar to the following to retrieve a JWT:

$ curl -s \
--user "client-application:password" \
--data "grant_type=password&username=demo&password=Ch4ng31t&scope=openid" \
http://openam.example.com:8088/openam/oauth2/access_token | jq .

{
  "access_token":"...",
  "scope":"openid",
  "id_token":"...",
  "token_type":"Bearer",
  "expires_in":3599
}

Add the following route to IG, and replace <jwt_value> with the value of the id_token returned in the previous step:

Linux
Windows

$HOME/.openig/config/routes/jwtvalidation.json

appdata\OpenIG\config\routes\jwtvalidation.json

{
  "name": "jwtvalidation",
  "condition": "${find(request.uri.path, '^/jwtvalidation')}",
  "capture": "all",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [{
        "type": "JwtValidationFilter",
        "config": {
          "jwt": "<jwt_value>",
          "failureHandler": {
            "type": "ScriptableHandler",
            "config": {
              "type": "application/x-groovy",
              "source": [
                "def response = new Response(Status.FORBIDDEN)",
                "response.headers['Content-Type'] = 'text/html; charset=utf-8'",
                "def errors = contexts.jwtValidationError.violations.collect{it.description}",
                "def display = \"<html>Can't validate JWT:<br> ${contexts.jwtValidationError.jwt} \"",
                "display <<=\"<br><br>For the following errors:<br> ${errors.join(\"<br>\")}</html>\"",
                "response.entity=display as String",
                "return response"
              ]
            }
          },
          "verificationSecretId": "verify",
          "secretsProvider": {
            "type": "JwkSetSecretStore",
            "config": {
              "jwkUrl": "http://openam.example.com:8088/openam/oauth2/connect/jwk_uri"
            }
          }
        }
      }],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/html" ]
          },
          "entity": "<html><body>Validated JWT:<br> ${contexts.jwtValidation.value}</body></html>"
        }
      }
    }
  }
}

Notice the following features of the route:

The route matches requests to /jwtvalidation.
The property secretsProvider declares a JwkSetSecretStore to validate secrets for signed JWTs, specifying the URL to a JWK set on AM that contains the signing keys.
If the filter validates the token, the StaticResponseHandler displays the JWT value from the context ${contexts.jwtValidation.value}. Otherwise, the ScriptableHandler displays the JWT value and a list of violations from the context ${contexts.jwtValidationError.violations}

Test the setup:
1. Access the route on http://openig.example.com:8080/jwtvalidation.
  
  The JWT is displayed.
2. In the route, invalidate the JWT by changing its value, and then access the route again.
  
  The value of the JWT, and the reasons that the JWT is invalid, are displayed.

Validate an Encrypted JWT

Set up keys and AM as described in Validating Encrypted Access_Tokens With the StatelessAccessTokenResolver and KeyStoreSecretStore.

In a terminal window, use a curl command similar to the following to retrieve a JWT:

$ curl -s \
--user "client-application:password" \
--data "grant_type=password&username=demo&password=Ch4ng31t&scope=myscope" \
http://openam.example.com:8088/openam/oauth2/access_token | jq .

{
 "access_token": "eyJ...pvw",
 "scope": "myscope",
 "token_type": "Bearer",
 "expires_in": 3598
 }

Add the following route to IG, and replace <jwt_value> with the value of the access_token returned in the previous step, and ig_keystore_directory with your directory:

Linux
Windows

$HOME/.openig/config/routes/jwtvalidation-encrypted

appdata\OpenIG\config\routes\jwtvalidation-encrypted

{
  "name": "jwtvalidation-encrypted",
  "condition": "${find(request.uri.path, '^/jwtvalidation-encrypted')}",
  "capture": "all",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "KeyStoreSecretStore-1",
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "<ig_keystore_directory>/IG_keystore.p12",
        "storeType": "PKCS12",
        "storePassword": "keystore.secret.id",
        "keyEntryPassword": "keystore.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "mappings": [
          {
            "secretId": "stateless.access.token.decryption.key",
            "aliases": [ "decryption-key" ]
          }
        ]
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [{
        "type": "JwtValidationFilter",
        "config": {
          "jwt": "<jwt_value>",
          "failureHandler": {
            "type": "ScriptableHandler",
            "config": {
              "type": "application/x-groovy",
              "source": [
                "def response = new Response(Status.FORBIDDEN)",
                "response.headers['Content-Type'] = 'text/html; charset=utf-8'",
                "def errors = contexts.jwtValidationError.violations.collect{it.description}",
                "def display = \"<html>Can't validate JWT:<br> ${contexts.jwtValidationError.jwt} \"",
                "display <<=\"<br><br>For the following errors:<br> ${errors.join(\"<br>\")}</html>\"",
                "response.entity=display as String",
                "return response"
              ]
            }
          },
          "secretsProvider": "KeyStoreSecretStore-1",
          "decryptionSecretId": "stateless.access.token.decryption.key"
        }
      }],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/html" ]
          },
          "entity": "<html>Validated JWT:<br> ${contexts.jwtValidation.value}</html>"
        }
      }
    }
  }
}

Notice the following features of the route compared to jwtvalidation.json :

The route matches requests to /jwtvalidation-encrypted.
The JwtValidationFilter uses the KeyStoreSecretStore in the heap to provide secrets for verification and decryption of the access_token. The secrets IDs are mapped in the KeyStoreSecretStore.
The KeyStoreSecretStore password is provided by the SystemAndEnvSecretStore in the heap.

Test the setup:
1. Access the route on http://openig.example.com:8080/jwtvalidation-encrypted.
  
  The JWT is displayed.
2. In the route, invalidate the JWT by changing its value, and then access the route again.
  
  The value of the JWT, and the reasons that the JWT is invalid, are displayed.

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

IG 7.1.2

JwtValidationFilter

Usage

Properties

Example

More Information