Package org.forgerock.openam.oauth2.token.macaroon

Class MacaroonToken<T extends IntrospectableToken>

  • Type Parameters:
    T - the type of token this is.
    All Implemented Interfaces:
    IntrospectableToken, Token
    @Evolving
public class MacaroonToken<T extends IntrospectableToken>
extends Object
implements IntrospectableToken
    An OAuth2 access or refresh token that is represented as a Macaroon. Macaroons allow caveats to be added to a token after it has been issued. Caveats restrict the scope, expiry time or other properties of the token.

    In addition to the supported AccessToken or RefreshToken methods, macaroon tokens expose additional supported methods for adding caveats from scripts and plugins.

    • Method Detail

      • addFirstPartyCaveat

        @Evolving
public T addFirstPartyCaveat​(String caveat)
        Adds a first-party caveat to the access token macaroon. AM supports caveats in JSON format in the following forms:
        • {"exp":12345} - reduces the expiry time of the token (in seconds since the UNIX epoch).
        • {"scope":"a b c"} - reduces the scope of the token.
        • {"aud": ["x", "y", "z"]} - reduces the audience of the token. A token without an audience restriction is assumed to be valid to access all resource servers.
        • {"cnf": ...} - adds a proof-of-possession confirmation key restriction, such as a mutual TLS certificate binding. Such a restriction can only be added once, and only if the underlying access token does not already have a confirmation key associated with it.
        Any unrecognized first-party caveats are returned from the token introspection endpoint as a JSON array under the non-standard "caveats" field.
        Parameters:
        caveat - the caveat to add as a string.
        Returns:
        this macaroon token
        See Also:
        addFirstPartyCaveat(JsonValue)

      • addFirstPartyCaveat

        @Evolving
public T addFirstPartyCaveat​(byte[] caveat)
        Adds a first-party caveat to the access token macaroon. AM supports caveats in JSON format in the following forms:
        • {"exp":12345} - reduces the expiry time of the token (in seconds since the UNIX epoch).
        • {"scope":"a b c"} - reduces the scope of the token.
        • {"aud": ["x", "y", "z"]} - reduces the audience of the token. A token without an audience restriction is assumed to be valid to access all resource servers.
        • {"cnf": ...} - adds a proof-of-possession confirmation key restriction, such as a mutual TLS certificate binding. Such a restriction can only be added once, and only if the underlying access token does not already have a confirmation key associated with it.
        Any unrecognized first-party caveats are returned from the token introspection endpoint as a JSON array under the non-standard "caveats" field.
        Parameters:
        caveat - the caveat to add as a string.
        Returns:
        this macaroon token
        See Also:
        addFirstPartyCaveat(JsonValue)

      • addFirstPartyCaveat

        @Evolving
public T addFirstPartyCaveat​(JsonValue caveat)
        Adds a first-party caveat to the access token macaroon. AM supports caveats in JSON format in the following forms:
        • {"exp":12345} - reduces the expiry time of the token (in seconds since the UNIX epoch).
        • {"scope":"a b c"} - reduces the scope of the token.
        • {"aud": ["x", "y", "z"]} - reduces the audience of the token. A token without an audience restriction is assumed to be valid to access all resource servers.
        • {"cnf": ...} - adds a proof-of-possession confirmation key restriction, such as a mutual TLS certificate binding. Such a restriction can only be added once, and only if the underlying access token does not already have a confirmation key associated with it.
        Any unrecognized first-party caveats are returned from the token introspection endpoint as a JSON array under the non-standard "caveats" field.
        Parameters:
        caveat - the caveat to add as a string.
        Returns:
        this macaroon token

      • addThirdPartyCaveat

        @Evolving
public T addThirdPartyCaveat​(String location,
                             SecretKey caveatKey,
                             byte[] caveat)
        Adds a third-party caveat to a macaroon. Third-party caveats are satisfied by the client obtaining a discharge macaroon from the named 3rd-party service. Discharge macaroons can be provided to AM's token introspection endpoint by using the non-standard X-Discharge-Macaroon header.

        Note: any unsatisfied 3rd-party caveats will cause the token to be rejected from the token introspection endpoint with an invalid_grant error code.

        Parameters:
        location - The location of the 3rd-party service, such as a URI. May be null.
        caveatKey - The key that will be used to sign the discharge macaroon. This should be generated fresh for each caveat by calling Macaroon.generateKey().
        caveat - the caveat that the 3rd-party service should verify. This should securely communicate the caveatKey to the 3rd-party service, for example by encrypting it with a public key of the 3rd-party service or by establishing a ticket via out of band communications. The details of how this is done are unspecified and need to be agreed between the AS and 3rd-party service.
        Returns:
        this macaroon token.

      • addThirdPartyCaveat

        @Evolving
public T addThirdPartyCaveat​(String location,
                             SecretKey caveatKey,
                             String caveat)
        Adds a third-party caveat to a macaroon. Third-party caveats are satisfied by the client obtaining a discharge macaroon from the named 3rd-party service. Discharge macaroons can be provided to AM's token introspection endpoint by using the non-standard X-Discharge-Macaroon header.

        Note: any unsatisfied 3rd-party caveats will cause the token to be rejected from the token introspection endpoint with an invalid_grant error code.

        Parameters:
        location - The location of the 3rd-party service, such as a URI. May be null.
        caveatKey - The key that will be used to sign the discharge macaroon. This should be generated fresh for each caveat by calling Macaroon.generateKey().
        caveat - the caveat that the 3rd-party service should verify. This should securely communicate the caveatKey to the 3rd-party service, for example by encrypting it with a public key of the 3rd-party service or by establishing a ticket via out of band communications. The details of how this is done are unspecified and need to be agreed between the AS and 3rd-party service.
        Returns:
        this macaroon token.