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