Add federated-authorization example

[sohanmaheshwar]

What

Adds a new federated-authorization example: a self-contained demo of federated authentication with centralized fine-grained authorization in SpiceDB.

Users log in through different identity providers (Keycloak OIDC and GitHub OAuth). Each external account (keycloak_account, github_account) binds to a canonical internal user, and a single SpiceDB instance enforces document access control across all of them — so users from different IdPs can share resources with each other.

Contents

• FastAPI app (app.py) with Keycloak + GitHub login flows
• SpiceDB schema (spicedb/schema.zed) with the *_account → bound_to → user binding pattern
• docker-compose.yml bringing up SpiceDB, Keycloak, and the app
• Preconfigured Keycloak realm with demo users, HTML templates, and a README with setup steps

Everything runs locally via docker compose. Secrets are demo placeholders only; no real credentials are included.

Notes

• The related docs tutorial lives at spicedb/tutorials/federated-authorization.

[miparnisari]

this button doesn't work - it takes me back to the login page which is great but it doesn't really log me out

[sohanmaheshwar]

I was testing this sample and stumbled upon a bug which I think could use some discussion. Basically there is a duplication of users if you restart the container, this is because in-memory SpiceDB loses IdP bindings on restart while SQLite persists → duplicate rows. (this also shows up when a user can share a document with themself).

To fix this, claude recommends:

Keep SpiceDB in-memory; the stack stays self-contained with no extra services.

- Add idp_type + idp_subject columns to the users table, with a UNIQUE(idp_type, idp_subject) constraint.
- On login, get_or_create_user becomes:
  a. Look up the SpiceDB binding (fast path) — if present, use it.
  b. Otherwise look up the internal UUID by (idp_type, idp_subject) in SQLite; if found, reuse it and re-write the SpiceDB binding (self-heals after a restart wiped it).
  c. Only mint a brand-new UUID when the identity is genuinely new.
- Footprint: small — one table change + logic in one function. App stays keycloak + spicedb(memory) + app.
- Trade-off: narrative shifts slightly — SpiceDB becomes the authorization store, and the app's own DB owns the identity mapping. (Arguably a cleaner separation, but it changes how the README tells the story.)

Option 2 — Persist SpiceDB via Postgres

Keep SpiceDB as the single source of truth for identity resolution, exactly as the README describes today (no app-side identity table).

- Switch SpiceDB from --datastore-engine=memory to postgres.
- Add a Postgres service (with its own volume) and run spicedb migrate head once before serve.
- Bindings then survive restarts, so no duplicates.
- Footprint: heavier — new service, a migration step, and startup ordering (app waits on spicedb, spicedb waits on migrate, migrate waits on postgres). App code unchanged.
- Trade-off: the "self-contained, zero-setup, in-memory" quality of the demo goes away.

I think for a sample app Option 1 is better. Would this resemble a production-ish pattern? AppDB owns identity mapping and SpiceDB does only authZ. I think @tstirrat15 's comment on the docs was something to this effect. imo, the postgres option is overkill for a demo.

[miparnisari]

What's wrong with postgres?

• Trade-off: the "self-contained, zero-setup, in-memory" quality of the demo goes away.

It would still be self-contained and zero-setup. You can have a docker-compose that does all of that for you. We have one that you can use, I use it all the time :) https://github.com/authzed/spicedb/blob/main/docker-compose.postgres.yaml