Package uk.co.spudsoft.jwtvalidatorvertx

Interface JwtValidator

All Known Implementing Classes:
JwtValidatorVertxImpl
public interface JwtValidator
Validate JWTs. There are two approaches that can be used for finding the keys necessary to validate the signature:
  • The caller passes in the issuer, the validator performs OpenID Discovery to find the JWKS URL and then finds the keys from there.
  • The configuration of the validator specifies a number of JWKS URLs.

The former configuration is appropriate when used in a SAAS application with many issuers, each of which has it's own JWKS. If the validator is not being used in a SAAS application, or the issuers in a SAAS application share keys, then the second approach is a lot more memory efficient.

An instance of JwtValidator can only support one of these two models, determined by the JsonWebKeySetHandler that it uses (and you probably only want one JwtValidator in your service).

When a dynamic configuration is used the issuer acceptability must pass three steps:

  • The issuer passed in to the JwtValidator must be non-null and acceptable.
  • The issuer found in the token must be non-null and acceptable.
  • The issuer passed in and the issuer in the token must be the same.

With a static configuration the passed in issuer is optional, and thus the first and last steps may be skipped. If an issuer is passed in to a static configuration all three steps will take place.

There are circumstances in which a client will want to use a static JwtValidator, but also to use the OpenIdDiscoveryHandler. This is OK, but the caching of JWKSs will not be shared between the two sides because there is a fundamental difference in requirements between the two. When the OpenIdDiscoveryHandler is used to find JWKs the key IDs are specific to the issuer, but the static configuration requires all key IDs to be globally unique.

The WebClient passed in to create the JwtValidator does not have to be dedicated to it.

Author:
jtalbut

  • Method Details

    • createDynamic

      static JwtValidator createDynamic(io.vertx.ext.web.client.WebClient webClient, IssuerAcceptabilityHandler issuerAcceptabilityHandler, Duration defaultJwkCacheDuration)
      Create a JwtValidatorVertx that will use an OpenIdDiscoveryHandler to find JWKs from any acceptable issuer.
      Parameters:
      webClient - The Vertx WebClient instance that will be used for asynchronous communication with JWKS endpoints.
      issuerAcceptabilityHandler - The object used to determine the acceptability of issuers.
      defaultJwkCacheDuration - Time to keep JWKs in cache if no cache-control: max-age header is found.
      Returns:
      A newly created JwtValidatorVertx.

    • createStatic

      static JwtValidator createStatic(io.vertx.ext.web.client.WebClient webClient, Collection<String> jwksEndpoints, Duration defaultJwkCacheDuration, IssuerAcceptabilityHandler issuerAcceptabilityHandler)
      Create a JwtValidatorVertx that will use a fixed set of URLs for downloading JWKs.
      Parameters:
      webClient - The Vertx WebClient instance that will be used for asynchronous communication with JWKS endpoints.
      jwksEndpoints - The object used to determine the acceptability of issuers.
      defaultJwkCacheDuration - Time to keep JWKs in cache if no cache-control: max-age header is found.
      issuerAcceptabilityHandler - The object used to determine the acceptability of issuers.
      Returns:
      A newly created JwtValidatorVertx.

    • create

      static JwtValidator create(JsonWebKeySetHandler jsonWebKeySetHandler, IssuerAcceptabilityHandler issuerAcceptabilityHandler)
      Create a JwtValidatorVertx.
      Parameters:
      jsonWebKeySetHandler - The JsonWebKeySet handler used for OpenID discovery and JWK Set discovery.
      issuerAcceptabilityHandler - The object used to determine the acceptability of issuers.
      Returns:
      A newly created JwtValidatorVertx.

    • getPermittedAlgorithms

      Set<String> getPermittedAlgorithms()
      Get a copy of the current set of permitted algorithms.
      Returns:
      a copy of the current set of permitted algorithms.

    • setPermittedAlgorithms

      JwtValidator setPermittedAlgorithms(Set<String> algorithms) throws NoSuchAlgorithmException
      Replace the current set of permitted algorithms with a new set.
      Parameters:
      algorithms - The new set of permitted algorithms.
      Returns:
      this for fluent configuration.
      Throws:
      NoSuchAlgorithmException - if any of the algorithms passed in are not recognised.

    • addPermittedAlgorithm

      JwtValidator addPermittedAlgorithm(String algorithm) throws NoSuchAlgorithmException
      Add a single algorithm to the current set of permitted algorithms.
      Parameters:
      algorithm - The algorithm to add to the current set of permitted algorithms.
      Returns:
      this for fluent configuration.
      Throws:
      NoSuchAlgorithmException - if the algorithm passed is not recognised.

    • setRequireExp

      JwtValidator setRequireExp(boolean requireExp)
      Set to true if the token is required to have an exp claim.
      Parameters:
      requireExp - true if the token is required to have an exp claim.
      Returns:
      this for fluent configuration.

    • setRequireNbf

      JwtValidator setRequireNbf(boolean requireNbf)
      Set to true if the token is required to have an nbf claim.
      Parameters:
      requireNbf - true if the token is required to have an nbf claim.
      Returns:
      this for fluent configuration.

    • setTimeLeeway

      JwtValidator setTimeLeeway(Duration timeLeeway)
      Set the maximum amount of time that can pass between the exp and now.
      Parameters:
      timeLeeway - the maximum amount of time that can pass between the exp and now.
      Returns:
      this for fluent configuration.

    • validateToken

      io.vertx.core.Future<Jwt> validateToken(String issuer, String token, List<String> requiredAudList, boolean ignoreRequiredAud)
      Validate the token and either return a failed Future or return a Future containing the JWT's constituent parts. There are two ways in which keys can be located for token verification:
      • If the issuer is not null it will be used to perform OpenID Discovery to locate the JWKS and thus to download the key.
      • If the issuer is null all of the configured JWKS endpoints will be queried to search for the key.
      In both cases the key will be cached according to the Cache-Control max-age parameter, or for at least the configured minKeyCacheLifetime. In the case of a cache miss the JWKS endpoints (either configured or discovered) will always be requeried, so there isn't much harm in using a long key cache lifetime.
      Parameters:
      issuer - The token issuer.
      token - The token.
      requiredAudList - List of audiences, all of which must be claimed by the token.
      ignoreRequiredAud - Do not check for required audiences.
      Returns:
      The token's parts.