Auther — Centralized Auth
You’ve probably written login code more than once: a users table, password hashes,
a session cookie, maybe a “sign in with Google” button. A centralized identity
provider (IdP) takes all of that off your plate. It runs sign-up, sign-in, password
hashes, 2FA, session tokens, and key rotation; your app just receives a signed JWT
and trusts it. Auther is that identity provider — built so you can run it yourself
instead of renting Auth0, Keycloak, or Ory.
Why centralize? Once you have more than one service — a web app, a mobile client, a couple of internal APIs — you do not want each one re-implementing login and guessing at who’s allowed to do what. Auther becomes the single source of truth for who someone is and what they can do, and every service trusts the same signed token.
That second half — what they can do — is what sets Auther apart from a plain login service. It ships a hybrid ReBAC + ABAC permission engine inspired by Google Zanzibar (Google’s permissions system that models access as relationships rather than roles). Permissions are computed from those relationships and embedded right in the JWT, so the common-case check is zero-latency — your service reads the token, no network call; only context-dependent decisions fall back to a live lookup.
This guide has two parts. Part 1 explains what Auther is — every subsystem, how
it decides who can do what, and how the six kinds of client connect to it. Part 2
is the part nobody warns you about: landing a centralized IdP into an app that already
owns its users table and a web of foreign keys, without a multi-week rewrite.
Who this is for
Section titled “Who this is for”This guide assumes you’re comfortable with general backend work — HTTP, REST, SQL, a web framework, and JWTs at a “I’ve used them” level. It does not assume you know OAuth2/OIDC internals, authorization theory, or how a permission engine works underneath. Those are exactly what we teach from the ground up.
- You’re a working backend engineer evaluating or adopting a centralized IdP, and you want to actually understand it — not just paste a quickstart.
- You’ve used auth (login forms, JWTs, OAuth buttons) but never built the provider side, and the terms OIDC, ReBAC, or Zanzibar are still fuzzy.
- You need to integrate auth into a real codebase with existing data, not a greenfield toy.
Part 1 · The Auther Server
Section titled “Part 1 · The Auther Server”How the identity provider is built and how it decides who can do what.
| Chapter | What it covers |
|---|---|
| Stack & Project Structure | The technology choices and how the codebase is laid out |
| Authentication System | better-auth config, the OIDC surface, sessions, JWKS rotation, clients |
| ReBAC & the Permission Engine | Relationship tuples, authorization models, the resolution algorithm |
| ABAC, Guards, Groups & Invites | Runtime Lua policies, server guards, group hierarchies, registration contexts |
| API Keys & Machine Access | Keys as first-class subjects and the key→JWT exchange |
| Pipelines, Webhooks & Observability | Lua lifecycle hooks, outbound webhooks, metrics |
| Client Integration (A–D) | Server web app, SPA, machine-to-machine, and mobile flows |
| Advanced Integration (E–F) | Multi-tenant SaaS, microservice mesh, and working with permissions |
| Configuration & Local Dev | Environment variables and the Docker dev stack |
Part 2 · Integrating Auther Into Your App
Section titled “Part 2 · Integrating Auther Into Your App”The Shadow-User pattern and a file-by-file Hono + Drizzle walkthrough for an app that already has a database.
| Chapter | What it covers |
|---|---|
| Who Owns the User Row? | The core problem and a per-column source-of-truth model |
| Four Integration Archetypes | The decision matrix: where the user row and permissions live |
| The Shadow-User Pattern | JIT provisioning plus lifecycle webhooks, the recommended default |
| Hono Walkthrough — Schema | Shrinking your users table and pruning what Auther now owns |
| Hono Walkthrough — Auth Core | JWT-verifying middleware, the webhook receiver, the admin client |
| Hono Walkthrough — Server Internals | Principals, keeping your authz package, and a safe cutover |
| End-to-End Flows | Six runtime traces from signup to deletion |
| Edge Cases Catalog | Thirty failure modes and how to defuse each |
| DX Stack, Libraries & Testing | A minimal production toolkit and a reusable middleware factory |
| Alternative System Shapes | The same patterns for SPAs, meshes, mobile, and legacy migrations |
| FAQ & Summary | Quick answers and the nine things to remember |