Class JwtValidator

java.lang.Object
com.revetsec.jose.JwtValidator

@ThreadSafe @CheckReturnValue public final class JwtValidator extends Object
Validates JWTs in the JWS compact serialization (RFC 7519, RFC 7515) signed with a public key, for one expected issuer.

The validateResult(String) operation runs the checks in a fixed order and stops at the first failure:

  1. the token's length, before it is examined any further;
  2. the compact serialization and the canonical base64url of every segment;
  3. the JOSE header: a strict JSON object whose alg is an allowed algorithm (compared exactly, so none in any case fails here); then no crit, b64 or zip; then no key or key location in the header (jwk, jku and x5u are rejected and never fetched); then an allowed typ; then no cty; then a kid, when present, that is a string of 1 to 256 characters;
  4. the signature's length and form for the algorithm, before any key is looked up, so a malformed signature never causes a key set fetch;
  5. the key, selected from the JwksSource by the header's kid and the algorithm; a remote source may fetch or refresh its key set here, on the calling thread;
  6. the signature, over the header and payload exactly as received;
  7. the claims: a strict JSON object whose registered claims have the right types; iss equal to the expected issuer; the key's JWK issuer member, when it has one, bound to iss; an expected audience in aud; exp, then iat, then nbf against the clock, with the clock skew; the required claims; and no cnf, because this validator does not check proof of possession.
A rejected token returns a JwtValidationResult.Rejected whose JoseException.Reason names the failed check. A remote source that cannot supply its key set throws a JwksUnavailableException, unchanged. Neither outcome nor exception diagnostics contain the token, a claim or a key ID.

Instances are immutable and safe for concurrent use. JwtValidator.Builder.build() does no I/O, even over a remote key source. Validators compare by reference.

Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • withIssuer

      Starts building a validator for tokens from issuer.
      Parameters:
      issuer - the expected iss, compared exactly, code point by code point, with no normalization: a trailing slash or a difference in case is another issuer
      Returns:
      a new builder
      Throws:
      NullPointerException - if issuer is null
      IllegalArgumentException - if issuer is empty
      Since:
      1.0.0
    • validateResult

      @CheckReturnValue public @NonNull JwtValidationResult validateResult(@NonNull String compactSerialization)
      Validates once and returns a success or a fixed local input rejection. Remote key-source failures remain exceptions; no rejected JWT, claims or credential are exposed. See the class description for the checks and their order.

      Over a RemoteJwksSource, this may fetch the key set on the calling thread, or wait for another caller's fetch, for up to the source's request timeout.

      Parameters:
      compactSerialization - untrusted compact token
      Returns:
      the validation outcome
      Throws:
      NullPointerException - if the token is null
      JwksUnavailableException - if remote keys are unavailable
      Since:
      1.0.0
    • toString

      Describes this validator's configuration.
      Overrides:
      toString in class Object
      Returns:
      the issuer, the key source and the checks' settings
      Since:
      1.0.0