projectbrain-Public/docs/MICROSOFT_ENTRA_LOGIN.md

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:

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.