Package org.forgerock.macaroons

Class 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 Detail

      • JsonCaveatVerifier

        public JsonCaveatVerifier()

    • Method Detail

      • 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.