Package org.forgerock.macaroons

Class JsonCaveatVerifier

java.lang.Object
org.forgerock.macaroons.JsonCaveatVerifier
All Implemented Interfaces:
CaveatVerifier
public final class JsonCaveatVerifier extends Object implements CaveatVerifier
Implements caveats that are structured as JSON objects. Each key-value pair in the object represents a condition to be satisfied: the key is a predicate symbol and the value is the arguments. For example, the object 

 {
     "exp": 1577836800,
     "aud": ["https://api.example.com"]
 }
Indicates that the macaroon expires at midnight on the 1st of January, 2020, and that the server at https://api.example.com is the intended audience.

See MacaroonVerifier for a description of naming conventions for methods in this class.

This class is not thread-safe and should be created fresh for each use.

  • Constructor Details

    • JsonCaveatVerifier

      public JsonCaveatVerifier()

  • Method Details

    • forDefaultCaveats

      public static JsonCaveatVerifier forDefaultCaveats(Instant timeOfUse, Duration allowedClockSkew)
      Constructs a caveat verifier that will verify a set of standard caveats:
      • "exp": time - checks that the current time is less than the given time. The time is a number of seconds since the UNIX epoch.
      • "nbf": time - checks that the current time is more than the given time. The time is a number of seconds since the UNIX epoch.
      Parameters:
      timeOfUse - the instant to use for checking time-based caveats.
      allowedClockSkew - the allowed clock skew when checking expiry or not-before times.
      Returns:
      the caveat verifier.

    • forDefaultCaveats

      public static JsonCaveatVerifier forDefaultCaveats(Instant timeOfUse)
      Constructs a caveat verifier that will verify a set of standard caveats:
      • "exp": time - checks that the current time is less than the given time. The time is a number of seconds since the UNIX epoch.
      • "nbf": time - checks that the current time is more than the given time. The time is a number of seconds since the UNIX epoch.
      No clock skew is allowed when using this method. Use forDefaultCaveats(Instant, Duration) if you want to tolerate some clock skew.
      Parameters:
      timeOfUse - the instant to use for checking time-based caveats.
      Returns:
      the caveat verifier.

    • satisfyTimeOfUse

      public JsonCaveatVerifier satisfyTimeOfUse(Instant timeOfUse, Duration allowedClockSkew)
      Constructs a caveat verifier that will verify a set of time of use caveats:
      • "exp": time - checks that the current time is less than the given time. The time is a number of seconds since the UNIX epoch.
      • "nbf": time - checks that the current time is more than the given time. The time is a number of seconds since the UNIX epoch.
      Parameters:
      timeOfUse - the time to use for checking time-based caveats.
      allowedClockSkew - the allowed clock skew when checking expiry or not-before times.
      Returns:
      the caveat verifier.

    • satisfyTimeOfUse

      public JsonCaveatVerifier satisfyTimeOfUse(Instant timeOfUse)
      Constructs a caveat verifier that will verify a set of time of use caveats:
      • "exp": time - checks that the current time is less than the given time. The time is a number of seconds since the UNIX epoch.
      • "nbf": time - checks that the current time is more than the given time. The time is a number of seconds since the UNIX epoch.
      No clock skew is allowed when using this method. Use satisfyTimeOfUse(Instant, Duration) if you want to tolerate some clock skew.
      Parameters:
      timeOfUse - the instant to use for checking time-based caveats.
      Returns:
      the caveat verifier.

    • satisfyExpiryTime

      public JsonCaveatVerifier satisfyExpiryTime(Instant timeOfUse, Duration allowedClockSkew)
      Constructs a caveat verifier that will verify any expiry time caveats of the form:
      • "exp": time - checks that the current time is less than the given time. The time is a number of seconds since the UNIX epoch.
      Parameters:
      timeOfUse - the instant to use for checking time-based caveats.
      allowedClockSkew - the allowed clock skew when checking expiry times.
      Returns:
      the caveat verifier.

    • satisfyNotBeforeTime

      public JsonCaveatVerifier satisfyNotBeforeTime(Instant timeOfUse, Duration allowedClockSkew)
      Constructs a caveat verifier that will verify any not-before time caveats of the form:
      • "nbf": time - checks that the current time is more than the given time. The time is a number of seconds since the UNIX epoch.
      Parameters:
      timeOfUse - the instant to use for checking time-based caveats.
      allowedClockSkew - the allowed clock skew when checking not-before times.
      Returns:
      the caveat verifier.

    • satisfyJsonCaveat

      public JsonCaveatVerifier satisfyJsonCaveat(String field, Predicate<JsonValue> verifier)
      Adds a verifier for a caveat specified as a JSON field. The verifier will be called to verify any field that has the given name. For example, to verify that our API URI is in any audience restriction for a macaroon you could use (but see satisfyAudience(String...)): 
      
 JsonCaveatVerifier verifier = new JsonCaveatVerifier()
      .satisfyJsonCaveat("aud", value -> value.asList().contains("https://api.example.com"));
      Parameters:
      field - the JSON field to register a verifier for.
      verifier - the caveat verifier.
      Returns:
      this verifier.

    • satisfyAudience

      public JsonCaveatVerifier satisfyAudience(String... audience)
      Satisfies any audience ("aud") caveat in the macaroon that contains at least one of the given audience values. The audience comparison will be case-sensitive.
      Parameters:
      audience - the allowed audience values.
      Returns:
      this verifier.

    • satisfyAudience

      public JsonCaveatVerifier satisfyAudience(Collection<String> audience)
      Satisfies any audience ("aud") caveat in the macaroon that contains at least one of the given audience values. Comparisons will be performed using audience.contains(...) so the case-sensitivity of the comparison will depend on the type of collection passed as an argument.
      Parameters:
      audience - the allowed audience values.
      Returns:
      this verifier.

    • satisfyClientCertificate

      public JsonCaveatVerifier satisfyClientCertificate(X509Certificate clientCertificate)
      Satisfies any caveat that requires the macaroon is only used on a channel that has been authenticated with a given X.509 client certificate. The verifier will satisfy a cnf (confirmation key) caveat with either of the two following thumbprint types:
      • x5t#S256 - the caveat value is a base64url-encoded SHA-256 hash of the certificate.
      • x5t#S512 - the caveat value is a base64url-encoded SHA-512 hash of the certificate.
      An example caveat satisfied by this method (when called with a matching certificate) is: 
      
 { "cnf": { "x5t#S256": "4bAzYPOjxr1StFEbwCefB7OKGxu3qyCdMYM_dhfidi8" } }
      Parameters:
      clientCertificate - the client certificate associated with this request.
      Returns:
      this verifier.

    • isSatisfied

      public boolean isSatisfied(Macaroon.Caveat caveat, Macaroon macaroon)
      Description copied from interface: CaveatVerifier
      Checks whether the given caveat is satisfied. Caveat verifiers should be quick to evaluate (ideally constant-time), as a macaroon may have a large number of caveats, as may any discharge macaroons. If caveat verifiers take a long time to run then an attacker may be able to use this as a denial of service attack vector by sending macaroons with a large number of expensive caveats. Where a potentially expensive operation is required, consider making it a 3rd-party caveat to offload the processing to a separate service with a simple discharge macaroon used to prove that it has been satisfied.
      Specified by:
      isSatisfied in interface CaveatVerifier
      Parameters:
      caveat - the caveat to verify.
      macaroon - the macaroon that the caveat is attached to.
      Returns:
      true if the caveat is satisfied, otherwise false.