Initial curated projectbrain source from 8a7b1e0651dbdab97d744cbd2e653ab3970ac6c5

docs/MICROSOFT_ENTRA_LOGIN.md

@@ -0,0 +1,41 @@
+# Microsoft Entra ID login
+
+ProjectBrain supports tenant-bound Microsoft Entra ID login through the server-side OpenID Connect authorization-code flow with PKCE. The local owner login remains available as a recovery route.
+
+## Entra app registration
+
+1. Create a single-tenant app registration named `ProjectBrain` in the intended Microsoft Entra tenant.
+2. Under **Authentication**, add a **Web** redirect URI (not SPA):
+
+   `https://projectbrain.example.test/api/auth/entra/callback`
+
+3. Create a client credential. Prefer a certificate credential where operational support is available; the current ProjectBrain runtime accepts a client secret.
+4. No Microsoft Graph application permissions are required. The login requests only `openid profile email`; email is display metadata and never an authorization key.
+
+## Server configuration
+
+Set these only in the server-side `.env` file:
+
+```dotenv
+PROJECTBRAIN_ENTRA_TENANT_ID=<Directory tenant ID>
+PROJECTBRAIN_ENTRA_CLIENT_ID=<Application client ID>
+PROJECTBRAIN_ENTRA_CLIENT_SECRET=<secret value, not secret ID>
+```
+
+Keep `PROJECTBRAIN_PUBLIC_URL=https://projectbrain.example.test` and `PROJECTBRAIN_DATA_SOURCE=database`. Restart or redeploy ProjectBrain after changing the values. Never place the client credential in a `VITE_` variable or browser configuration.
+
+## First-time account link
+
+1. Sign in with the local owner account.
+2. Open **Settings → Microsoft Entra ID**.
+3. Choose **Mijn Microsoft-account koppelen** and complete Microsoft sign-in.
+4. Sign out. **Aanmelden met Microsoft** is now available on the login screen.
+
+ProjectBrain binds the identity to the immutable Entra tenant ID plus object ID (`tid` + `oid`). It deliberately does not auto-link on email address or user principal name.
+
+## Recovery and rotation
+
+- Keep the local owner password in the normal secret-management process.
+- Unlinking Entra requires the local owner password in addition to the active session and CSRF token.
+- Rotate the Entra client credential before expiry and update only the server `.env` value.
+- An Entra callback state is one-time, stored only as a SHA-256 hash, and expires after ten minutes.