Blog »

Updated token validation in Nimbus JOSE+JWT 8

2019-10-21

Version 8 of the Nimbus JOSE+JWT library updates the token validation framework.

When creating a JOSEProcessor or JWTProcessor they can now be configured to accept only tokens with a given typ (type) header parameter. Use of this header parameter is recommended to prevent accidental or malicious passing of a JWS or JWE of another type which happens to rely on identical claims.

For this reason the new JWT Profile for OAuth 2.0 Access Tokens sets this header to "at+jwt".

For example:

{
  "alg" : "RS256",
  "typ" : "at+jwt",
  "kid" : "AhXoh4fe"
}

The DefaultJWTClaimsVerifier was also updated, to enable configuration of exact audience and other claim matching, lists of JWT claim names that must be present and claims which presence is prohibited.

Here are some sample validation rules for an access token:

  • Expected audience (aud): https://demo.c2id.com/userinfo
  • Exact match claims: iss = https://demo.c2id.com
  • Names of claims that must be present: sub, cid, exp, scp
  • Names of prohibited claims: nonce

Example token claims:

{
  "iss" : "https://demo.c2id.com",
  "aud" : "https://demo.c2id.com/userinfo"
  "sub" : "alice",
  "cid" : "000123",
  "exp" : 1460345736,
  "scp" : ["openid","email","profile"],
  "clm" : ["!5v8H"],
  "uip" : {"groups":["admin","audit"]}
}

Use of the new features is explained in the updated article for validating JWT-encoded access tokens.

Release notes

version 8.0 (2019-10-15)

  • Adds new JOSEObjectTypeVerifier interface for verifying the "typ" (type) header parameter of processed JOSE objects. A configurable DefaultJOSEObjectTypeVerifier is provided.
  • Updates the ConfigurableJOSEProcessor interface with methods for setting a JWS and a JWE JOSEObjectTypeVerifier (API breaking change).
  • Updates the DefaultJOSEProcessor and DefaultJWTProcessor classes to support JWS and JWE "typ" (type) header parameter verification via the new JOSEObjectTypeVerifier interface.
  • Makes JOSEObject.hashCode() and JOSEObject.equals() case insensitive.
  • Removes exception caching in DefaultJOSEProcessor and DefaultJWTProcessor (iss #229).
  • JWK.parseFromPEMEncodedObjects should throw a JOSEException on a missing PEM-encoded public key required to construct the JWK (iss #331).

version 8.1 (2019-10-15)

  • Extends DefaultJWTClaimsVerifier with configurable checks for "iat", "exp", "nbf", "iss" and "aud".

version 8.2 (2019-10-17)

  • Redesigns DefaultJWTClaimsVerifier to support complex audience checks, arbitrary exact claim matching, presence and prohibited checks.