Macaroons Escalated Quickly

Summary

Fly.io built a Macaroons-based security token system after finding its API tokens too powerful for expressing scoped permissions and roles. The design starts with a user-linked, HMAC-signed bearer token and chains caveats through HMAC, while checking every caveat independently so each added restriction can only weaken authorization. It models organizations, apps, machines, and volumes with first-party caveats, and also includes third-party caveats, service-token transformations, machine locking, nonce-based revocation, and expiration handling across customer workloads. The resulting system lets users create roles without changing the platform and supports SSO, plugins, and traceable inter-service authorization, although the author acknowledges extra complexity and awkward ways to express some roles.

Takeaways

1. 1

   Each caveat is checked independently, and every added caveat can only weaken a token’s authorization; a token with no caveats is unrestricted and should not be honored.

2. 2

   Fly.io models permissions through caveats covering organizations, apps, machines, and volumes, allowing users to create administrator, auditor, deployment, and other roles without platform changes.

3. 3

   The implementation supports service tokens for longer-lived distributed workflows, machine-specific attenuation, nonce-based revocation, SSO, plugins, and traceable inter-service authorization, but restrictive caveats can express some roles awkwardly.