[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.

[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

[sohanmaheshwar]

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

Yep, like for the RAG demos I use a vector db in a docker container as well. just wondering if in this case, having a postgres instance to do state management takes away from the central teaching concept. Like the architecture diagram gets one more block, and there's a new section in the docs etc.

OTOH, the 'add a new field' is a classic LLM way to solve a problem although in this particular case it maybe ok?

Not sure which is the better approach here.

[sohanmaheshwar]

Resolved the duplicate-users discussion: back SpiceDB with Postgres

Picked this back up and went with @miparnisari's suggestion — switched SpiceDB from the in-memory engine to a persistent Postgres datastore. That turned out to be the real root cause, and it's broader than just duplicate users: with --datastore-engine=memory, a restart wipes every SpiceDB relationship — the IdP bindings and the document grants. The app's SQLite table survived, so a returning user found no bound_to binding, minted a fresh UUID, and became a duplicate users row; shared documents also silently lost their grants. Persisting SpiceDB fixes all of it at the source, with no application-code change.

The major change, at a glance

Before — in-memory; a restart wipes everything:

flowchart LR
    U["User's Browser"]
    subgraph IdP["Identity Providers"]
      KC["Keycloak (Org A)<br/>OIDC"]
      GH["GitHub (Org B)<br/>OAuth"]
    end
    A["FastAPI app"]
    DB[("SQLite<br/>profiles + doc metadata")]
    S["SpiceDB"]
    MEM[/"in-memory datastore<br/>lost on restart"/]:::warn
    U <--> A
    U -->|login| KC
    U -->|login| GH
    A -->|token exchange| KC
    A -->|token exchange| GH
    A -->|gRPC| S
    A --> DB
    S --- MEM
    classDef warn fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#7c2d12;

Loading

After — Postgres-backed; bindings and grants survive a restart:

flowchart LR
    U["User's Browser"]
    subgraph IdP["Identity Providers"]
      KC["Keycloak (Org A)<br/>OIDC"]
      GH["GitHub (Org B)<br/>OAuth"]
    end
    A["FastAPI app<br/>(unchanged)"]
    DB[("SQLite<br/>profiles + doc metadata")]
    S["SpiceDB"]
    PG[("PostgreSQL<br/>durable relationship store")]:::new
    MIG["datastore migrate head<br/>one-shot on startup"]:::new
    U <--> A
    U -->|login| KC
    U -->|login| GH
    A -->|token exchange| KC
    A -->|token exchange| GH
    A -->|"gRPC: Check / Lookup / Write"| S
    A --> DB
    S -->|reads + writes| PG
    MIG -.->|creates schema| PG
    classDef new fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;

Loading

The whole delta is the two green blocks — a postgres service and a one-shot datastore migrate head. The federated-identity story (IdPs → app → SpiceDB → documents) is untouched; app code and the SpiceDB schema are unchanged.

Verified: after docker compose restart spicedb, a returning Keycloak login resolves to the same user:<uuid> (one users row, not two) and a previously-owned document is still viewable.

Also in this update

• RP-initiated Keycloak logout that actually ends the SSO session. The realm's frontendUrl is pinned to the public address so the id_token's issuer matches the end-session endpoint — without it Keycloak rejected the id_token_hint and the next login silently re-authenticated.
• Permission checks fail closed everywhere — a SpiceDB error denies (and logs) instead of 500-ing or being silently swallowed — and the document-open path now uses a single CheckBulkPermissions instead of three sequential checks.
• Pinned authzed/spicedb to a release tag, and refreshed the docs: a persistence section, a visual "How the app uses SpiceDB" overview, and the architecture diagram (now showing the Postgres datastore).

[tstirrat15]

LGTM