From 5bf307606a1107bb591ce082e1cdd79ce82d1643 Mon Sep 17 00:00:00 2001
From: Sohan Maheshwar <1119120+sohanmaheshwar@users.noreply.github.com>
Date: Mon, 26 Oct 2026 16:10:12 +0100
Subject: [PATCH] federated-authorization: explain why identities bind to a
 single user

Adds a short note after the schema explaining the design choice, the
user#identity alternative and its trade-offs, and that consolidating on
the internal user ID is the long-term goal.
---
 federated-authorization/README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/federated-authorization/README.md b/federated-authorization/README.md
index 194190a..87be55e 100644
--- a/federated-authorization/README.md
+++ b/federated-authorization/README.md
@@ -44,6 +44,8 @@ definition document {
 }
 ```
 
+**Why bind identities to a single `user`?** Every grant targets the internal `user`, so permissions survive swapping or adding IdPs, and each login is resolved to that user once. An alternative is to grant on a `user#identity` permission that unions every linked account. That lets you check directly with any IdP ID, but checks on the internal user ID then need an extra `self` relation, and creating or sharing documents still needs the internal user. The goal here is to consolidate on the internal ID, at which point the login lookup goes away.
+
 ### Persistence
 
 SpiceDB is backed by **PostgreSQL** (`--datastore-engine=postgres`), so every relationship — the IdP→user bindings *and* the document grants — survives a restart of the stack. A one-shot `datastore migrate head` service initializes the Postgres schema before SpiceDB starts serving.