Design and Implementation of Himeji: A Zanzibar‑Based Centralized Authorization System at Airbnb

Airbnb's engineering team migrated from a monolithic Ruby on Rails architecture to a Service‑Oriented Architecture (SOA). In the original Rails system each resource had its own API with built‑in authorization checks, which were easy to manage because all access paths were centralized.

During the transition to SOA, authorization checks were moved to presentation services. This introduced two major problems:

Duplicate and hard‑to‑manage checks: Multiple presentation services accessed the same underlying data and each implemented its own authorization logic, leading to inconsistencies.

Fan‑out dependencies: Authorization checks often required calls to other services, increasing latency and reducing reliability.

To address these issues, Airbnb made two key changes:

Authorization checks were moved from presentation services into data services, eliminating duplication.

A centralized authorization system called Himeji was built on top of the Zanzibar model. Himeji stores permission data and provides a single source of truth for checks, shifting heavy read‑side fan‑out to the write path.

Himeji exposes an API for data services to perform checks. The API signature is illustrated in the following code snippet: check(entity: "LISTING : 10", relation: WRITE, userId: 123) Permissions are represented as triples of the form entity # relation @ principal. The components are:

Entity: composed of entity type : entity id : entity part (e.g., LISTING : 10 : DESCRIPTION).

Relation: describes the action or role (e.g., OWNER, READ, WRITE, HOST, DENY_VIEW).

Principal: an authenticated user or a reference to another entity (e.g., User(123) or Reference(LISTING:15)).

Configuration is expressed in a YAML‑like language that maps permissions to set algebra, allowing developers to define unions of relations. An example configuration:

LISTING:
  '#WRITE':
    union:
      - '#WRITE'
      - '#OWNER'
  '#READ':
    union:
      - '#READ'
      - '#WRITE'

When a check is performed, Himeji expands the requested relation using the configured unions. For instance, a request to check WRITE on a listing will also consider OWNER permissions.

Sample query results generated by Himeji:

Query LISTING : 10 # WRITE @ User(123) => Empty
Query LISTING : 10 # OWNER @ User(123) => Match User(123)

Another example demonstrates a read request for a listing’s location by a guest user: check(LISTING : 10 : LOCATION # READ, User(456)) Himeji translates this into two database queries:

Query LISTING : 10 # RESERVATION => Match Reference(RESERVATION:500)
Query LISTING : 10 # OWNER @ User(456) => Empty

Follow‑up query resolves the reservation reference:

Query RESERVATION : 500 # GUEST @ User(456) => Match User(456)

The system architecture consists of three layers:

Orchestration layer: receives client requests, generates data‑fetch plans based on configuration, and routes via consistent hashing.

Caching layer: sharded and replicated per availability zone, filters cache misses before hitting the database, aiming for ~98% hit rate.

Data layer: a logically sharded database (Airbnb uses Amazon Aurora).

Key architectural differences from the original Zanzibar design include separating orchestration from caching, using cache‑invalidation based on database changes, and leveraging Aurora instead of Spanner.

Performance metrics show that Himeji has been production‑stable for over a year, scaling from 0 to 850,000 entities per second while maintaining high availability:

Availability 99.9990%
P50 Latency 1.8 ms
P95 Latency 7 ms
P99 Latency 12 ms

To ease adoption, Airbnb built several tools: data back‑fill pipelines using Apache Airflow and Spark, automatic Java/Scala code generation, a “fat” HTTP client with logging and metrics, and a UI for debugging permission issues.

In conclusion, Himeji unifies Airbnb’s authorization data and logic, extending Zanzibar’s scalability and performance while handling billions of relationships and serving nearly one million entity checks per second with low latency and high availability.