Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud
📜 Abstract
Controlled sharing is fundamental to distributed systems; yet, on the Web, and in the Cloud, sharing is still based on rudimentary mechanisms. More flexible, decentralized cryptographic authorization credentials have not been adopted, largely because their mechanisms have not been incrementally deployable, simple enough, or efficient enough to implement across the relevant systems and devices. This paper introduces macaroons: flexible authorization credentials for Cloud services that support decentralized delegation between principals. Macaroons are based on a construction that uses nested, chained MACs (e.g., HMACs [43]) in a manner that is highly efficient, easy to deploy, and widely applicable. Although macaroons are bearer credentials, like Web cookies, macaroons embed caveats that attenuate and contextually confine when, where, by who, and for what purpose a target service should authorize requests. This paper describes macaroons and motivates their design, compares them to other credential systems, such as cookies and SPKI/SDSI [14], evaluates and measures a prototype implementation, and discusses practical security and application considerations. In particular, it is considered how macaroons can enable more fine-grained authorization in the Cloud, e.g., by strengthening mechanisms like OAuth2 [17], and a formalization of macaroons is given in authorization logic.
✨ Summary
Summary
The paper introduces macaroons, bearer authorization credentials built from chained HMACs. A macaroon can be delegated by appending caveats that only restrict authority, such as limiting operations, objects, time periods, client context, or requiring approval from third-party services. The paper also describes recursive third-party caveat discharges, request binding to prevent discharge-token reuse, implementation considerations, revocation strategies, privacy properties, and an authorization-logic formalization.
The central engineering contribution is the combination of bearer-token deployability with decentralized attenuation and contextual authorization. HMAC-based construction makes minting and verification substantially cheaper than comparable public-key operations, while retaining support for short-lived and narrowly scoped credentials. The principal limitation is that HMAC-based macaroons are verifiable only by the target service, unlike credentials based on publicly verifiable signatures.
Influence and adoption
The design has been implemented in reusable libraries, including libmacaroons and Python implementations, which provide APIs for minting, attenuation, verification, and third-party caveats. (github.com)
A concrete production use is Lightning Network Daemon (lnd), which uses macaroons as the default authentication and authorization mechanism for RPC access, including separate administrative, read-only, and invoice-related credentials. (github.com)
The same credential pattern was subsequently incorporated into the L402 protocol, where a macaroon is combined with a Lightning payment preimage to authorize paid HTTP or gRPC API access. (github.com)
Macaroons have also been considered as one of the authorization mechanisms usable by the WLCG HTTP third-party-copy ecosystem, alongside OAuth, OpenID Connect, and SciTokens. (arxiv.org)