Validating an Access Token

OAuth 2 Resource Servers restrict access to APIs by requiring a valid OAuth 2 access token to be present in the Authorization header as a bearer token (example: Authorization: Bearer ACCESS_TOKEN). It is the Resource Server’s responsibility to properly validate the access token.

In addition to validating the access token as a JWT, a Resource Server must validate sender-constrained access tokens against a required DPoP proof.

Validate the Access Token JWT

The access token will be provided in the Authorization header preceded by the string Bearer.

A JWT library should be used to validate the token. When validating time based claims such as exp and iat, most JWT libraries allow configuration of a clock drift. A clock drift of 60 seconds or less should be used.

1. Validate the ACCESS_TOKEN as a signed JWT. The ACCESS_TOKEN signature should be validated against the public key published in the JWKS_URL by the Jack Henry Authorization Server. Multiple keys may be present in the JWKS_URL. The kid header in the ACCESS_TOKEN JWT will specify which key is to be used for validation.
2. Ensure that the exp claim is in the future.
3. Ensure that the iat claim is now or in the past.
4. Ensure that the access token does not have a cnf claim or perform all the validation for a sender constrained access token and require a valid DPoP header.

Validate a Sender Constrained Access Token

The access token will be provided in the Authorization header preceded by the string DPoP (example: Authorization: DPoP ACCESS_TOKEN). The access token is required to be sender constrained meaning proof of ownership must also be provided. See Demonstrating Proof of Possession (DPoP) for more details.

When provided with a DPoP scheme, the access token must contain a cnf claim. If a cnf claim is missing, the token is not sender-constrained. The Resource Server must ensure a valid DPoP proof is present. See https://datatracker.ietf.org/doc/html/rfc9449#name-checking-dpop-proofs

The following checks must all be performed when the DPoP scheme is used or the Access Token contains a cnf claim. The checks may be performed in any order.

1. Ensure only one DPoP header is present on the request.
2. The DPoP HTTP request header field value is a single and well-formed JWT.
3. The DPoP JWT includes all the required claims:
   • jti
   • htm
   • htu
   • iat
   • ath
4. The typ header of the DPoP JWT is the value “dpop+jwt”.
5. The alg header of the DPoP JWT is one of the supported algorithms and is not none. Resource Servers must support all the DPoP algorithms.
6. The DPoP JWT signature verifies with the public key contained in the jwk header of the DPoP JWT.
7. The jwk header of the DPoP JWT does not contain a private key.
8. The htm claim matches the HTTP method of the current request.
9. The htu claim matches the HTTP URI value for the HTTP request in which the JWT was received, ignoring any query and fragment parts.
10. The creation time of the JWT, as determined by the iat claim is within an acceptable window. 60 seconds is the recommended lifetime a Resource Server should support (in addition to clock drift).
11. The value of the ath claim equals the result of a base64url encoding the SHA-256 hash of ASCII encoding the Access Token’s raw value.
12. The JWT thumbprint of the jwk header of the DPoP JWT matches the jkt key of the cnf claim in the Access Token. See https://datatracker.ietf.org/doc/html/rfc7638.

In addition, Resources Servers should do the following:

1. Use syntax-based normalization before comparing the htu claim.
2. Use scheme-based normalization before comparing the htu claim.
3. Ensure that the jti value has not been seen within a reasonable time window. Example: if the iat claim is allowed to be 60 seconds old and a clock-drift of 60 seconds is used, a jti value should be unique within a 2 minute window.

Additional Validation

A valid Access Token will contain the following claims which a Resource Server may use to further validate the call.

• client_id - The OAuth client id of the calling application
• institutionId - The universal institution id in which the OAuth client id is configured.
• sub - The associated user id of the caller. This is either the human who consented for the authorization code flow or the service account associated with the client credentials flow. The sub claim can be used to validate the permissions of the caller.