Role-Based Access Control

The Problem

As applications grow beyond a single user, you need to control who can do what. A junior developer shouldn’t delete production databases. A team member shouldn’t see billing details. A viewer shouldn’t edit documents. Role-Based Access Control (RBAC) assigns permissions to roles, and roles to users — but production systems need more: hierarchical roles, resource-level permissions, attribute-based policies, and real-time permission changes. The authorization check must be fast (sub-millisecond), consistent, and auditable, sitting on every request’s critical path.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

Scoped Roles and Resource-Level Permissions

Basic RBAC assigns global roles — “User X is an admin.” But most apps need scoped roles — “User X is an admin OF project Y but only a viewer OF project Z.”

Implementation: Add scope fields to the user-role assignment:

• scope_type: “organization”, “project”, “team”, “document”
• scope_id: the specific resource ID

Permission check flow:

1. User requests to edit Project Y
2. Look up user’s roles scoped to Project Y
3. Also look up roles scoped to Project Y’s parent (Organization Z) — role inheritance
4. Check if any of those roles include the “project:edit” permission
5. Allow or deny

Hierarchy: Permissions inherit downward. An org admin is implicitly a project admin for all projects in the org. Implement by walking up the resource hierarchy during permission checks. Cache the effective permissions per (user, scope) pair.

Performance: With scoped roles, the permission check involves multiple lookups. Pre-compute and cache the effective permission set per user-scope combination. Invalidate cache on role changes (pub/sub notification from the role service).

Google Zanzibar and ReBAC

Google’s Zanzibar paper (2019) introduced a scalable authorization system based on relationship tuples.

Core concept: Authorization data is stored as tuples: (object, relation, user). For example:

• (doc:readme, owner, user:alice) — Alice owns the readme doc
• (folder:eng, viewer, team:engineering#member) — Engineering team members can view the eng folder
• (doc:readme, parent, folder:eng) — readme doc is in the eng folder

Permission check: “Can Alice view doc:readme?” The system checks:

1. Is Alice a direct viewer of doc:readme? → No
2. Does doc:readme have a parent? → Yes, folder:eng
3. Is Alice a viewer of folder:eng? → Check if Alice is a member of team:engineering → Yes!
4. Permission granted via relationship chain.

Open-source implementations:

• SpiceDB (AuthZed) — Go-based, gRPC API, closest to Zanzibar
• OpenFGA (Auth0/Okta) — supports multiple storage backends
• Permify — Kubernetes-native, schema-first approach

ReBAC is ideal when your permission model mirrors your data hierarchy (organizations → projects → resources).

Performance and Caching Strategy

Authorization sits on the hot path of every request. It must be fast.

Caching layers:

1. In-process cache (LRU, 1000 entries, 30s TTL): Fastest. Caches (user_id, permission, scope) → boolean. Hit rate: 60-80% for typical web apps.
2. Redis cache (60s TTL): Shared across instances. Caches user’s effective role set per scope. Hit rate: 90%+.
3. Database (source of truth): Only hit on cache miss. Must be fast — proper indexes on user_id, role_id, scope columns.

Cache invalidation: When a role assignment changes:

1. Invalidate the user’s cache entries (in-process + Redis)
2. Publish an event so all instances invalidate their local cache
3. For security-critical changes (role revocation), force re-evaluation by bumping a version counter

Batch prefetching: For UI pages that show multiple resources, prefetch permissions for all visible resources in one batch call. “Can user X do [view, edit, delete] on resources [A, B, C, D]?” — single round-trip returning a permission matrix.

Latency targets: In-process cache hit: <0.01ms. Redis cache hit: <1ms. Database lookup: <5ms. Any authorization check >10ms indicates a problem.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Role-Based Access Control

You are an expert software architect and teacher. I want to understand role-based access control as a practical system design capability. (Permission models, policy engines, and row-level security for multi-user applications).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

As applications grow beyond a single user, you need to control who can do what. A junior developer shouldn't delete production databases. A team member shouldn't see billing details. A viewer shouldn't edit documents. Role-Based Access Control (RBAC) assigns permissions to roles, and roles to users — but production systems need more: hierarchical roles, resource-level permissions, attribute-based policies, and real-time permission changes. The authorization check must be fast (sub-millisecond), consistent, and auditable, sitting on every request's critical path.

## Architectural Approaches

<ApproachList>
<Approach
  name="Simple RBAC (Role → Permissions)"
  pros={[
    'Simple to understand, implement, and audit',
    'Works well for applications with clear role hierarchies',
    'Fast evaluation — single lookup per request',
    'Easy to explain permission model to end users',
  ]}
  cons={[
    'Role explosion — too many roles for fine-grained needs',
    'No resource-level permissions (can edit ALL documents, not specific ones)',
    'Adding a new permission requires updating role definitions',
    "Doesn't handle complex conditions (time-based, attribute-based)",
  ]}
>
Define a fixed set of roles (admin, editor, viewer), each with a set of permissions (create, read, update, delete). Assign roles to users. On each request, check if the user's role includes the required permission. Implemented ...

[Full prompt copied to clipboard]