Operationalizing Macaroons

1 We’ve spent too much time talking about security tokens, and about Macaroon tokens in particular. Writing another Macaroon treatise was not on my calendar. But we’re in the process of handing off our internal Macaroon project to a new internal owner

Fly.io logo
Fly.io
•
Thomas Ptacek
•14 min read•advanced•
--
•View Original
DockerNATSPrometheusRustSQLiteVault

Overview

The article discusses the operationalization of Macaroon tokens at Fly.io, detailing their implementation, benefits, and challenges. It highlights the unique features of Macaroons, including their online-stateful nature and the use of a dedicated database system called tkdb for managing token data securely.

What You'll Learn

1

How to implement a secure token management system using Macaroons

2

Why to keep sensitive token data away from complex code

3

How to effectively manage token revocation in a distributed system

4

When to use caching for Macaroon verification to improve performance

Prerequisites & Requirements

  • Understanding of bearer tokens and their use in API security
  • Familiarity with SQLite and its operational characteristics(optional)

Key Questions Answered

What are Macaroon tokens and how do they work?
Macaroon tokens are bearer tokens that utilize a chained-HMAC construction, allowing users to scope down their tokens independently. This means users can minimize their token privileges for specific API operations, enhancing security by only transmitting the necessary permissions.
How does Fly.io manage the database for Macaroon tokens?
Fly.io uses a dedicated system called tkdb, which is a lightweight Go application managing a SQLite database. This database is designed to be simple, secure, and isolated from the primary API cluster to enhance scalability and security.
What challenges does Fly.io face with Macaroon token verification?
One major challenge is that Macaroon verification is online-stateful, requiring connectivity to a database for nonce verification. This can lead to issues with network reliability, prompting the use of caching strategies to mitigate connectivity problems.
How does Fly.io handle token revocation?
Fly.io maintains a blacklist for revoked tokens in a database, ensuring that once a token is revoked, it cannot be used again. The revocation process involves adding the token's nonce to this blacklist, which is checked during verification.

Key Statistics & Figures

tkdb database size
a couple dozen megs
This size indicates that the database is efficient and only stores essential information related to token management.
PITR recovery time
just seconds
This rapid recovery capability highlights the efficiency of the database management system in place.
Cache hit ratio for verification
over 98%
This statistic demonstrates the effectiveness of caching in reducing the need for online verification.

Technologies & Tools

Some links below are affiliate links. We may earn a commission if you make a purchase.

Database
Sqlite
Used for managing token data in the tkdb system.
Storage
Litefs
Provides distributed SQLite management and point-in-time recovery.
Replication
Litestream
Used for continuous backup and replication of SQLite databases.
Security Protocol
Noise
Implemented for secure communication between services in the token management system.

Key Actionable Insights

1
Implement a dedicated token management system to enhance security and reliability.
By isolating token management from the primary API, you can prevent security vulnerabilities that arise from complex code interactions, ensuring that sensitive operations remain secure.
2
Utilize caching strategies for token verification to improve performance.
Given the high cache hit ratio of over 98% for Macaroon verifications, implementing a caching layer can significantly reduce the load on your database and improve response times.
3
Regularly review and update your token revocation strategies.
Since token revocation is critical for maintaining security, ensure that your system can handle revocations efficiently and that clients are notified of changes to token validity.

Common Pitfalls

1
Assuming that token revocation can be an afterthought can lead to security vulnerabilities.
It's crucial to have a robust revocation system in place to avoid issues like 'cosmetic logout', where users believe they have logged out but can still access resources.

Related Concepts

Bearer Tokens
Hmac Construction
Token Revocation Strategies
Caching Mechanisms