Demo content from demo/admin-guide (0c17989)

entra-id/index.md

@@ -0,0 +1,77 @@
+---
+id: entra-id
+title: Microsoft Entra ID
+description: Registering an app in Entra and pointing f451's OIDC configuration at it, step by step.
+tags: [admin, auth, entra]
+lang: en
+---
+
+# Microsoft Entra ID
+
+Entra ID is a standard OpenID Connect provider from f451's point of view —
+nothing here is Entra-specific in the code, only in the app registration
+steps below.
+
+## 1. Register an application
+
+In the Entra admin center, create a new **app registration**:
+
+- **Single tenant** (unless you specifically need multi-tenant sign-in).
+- **Redirect URI**, platform *Web*: `https://<host>/auth/callback` — this
+  must match `F451_OIDC_REDIRECT_URL` exactly, including scheme and any
+  trailing slash.
+- Under **Certificates & secrets**, create a **client secret**.
+
+> [!WARNING]
+> Client secrets expire. Note the expiry date somewhere your team actually
+> looks (a calendar reminder, not just the Entra portal) — an expired
+> secret takes sign-in down for everyone until it is rotated. Rotating it
+> means generating a new secret in Entra and updating
+> `F451_OIDC_CLIENT_SECRET`, then restarting the `api` service.
+
+## 2. Configure the ID token claims
+
+Recommended: add the optional claim **`email`** to the ID token (**Token
+configuration** → **Add optional claim** → ID). f451 reads the user's
+email from the `email` claim, falling back to `preferred_username` or
+`upn` if either of those looks like an email address (contains `@`).
+Without a usable email claim, sign-in still works, but the identity f451
+records for that person is less predictable.
+
+## 3. Restrict who may sign in
+
+By default, anyone in the tenant with access to the app can sign in. To
+restrict that, open the **enterprise application** for this app
+registration and turn on **Assignment required** under **Properties**,
+then assign the users or groups who should have access under **Users and
+groups**. This is the only access control at the sign-in layer — it does
+not grant access to any space; that still comes from the person's Forgejo
+or GitHub permissions (see [[sign-in-options]]).
+
+## 4. Configure f451
+
+Set on the `api` service:
+
+| Variable | Value |
+|---|---|
+| `F451_OIDC_ISSUER` | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
+| `F451_OIDC_CLIENT_ID` | the app registration's Application (client) ID |
+| `F451_OIDC_CLIENT_SECRET` | the client secret from step 1 |
+| `F451_OIDC_REDIRECT_URL` | `https://<host>/auth/callback` |
+| `F451_TOKEN_KEY` | 32 random bytes, base64-encoded (`openssl rand -base64 32`) — encrypts stored provider tokens, independent of Entra |
+| `F451_OIDC_PROVIDER_NAME` | optional, e.g. `Microsoft Entra` — labels the sign-in button "Sign in with Microsoft Entra"; unset shows a plain "Sign in" |
+
+f451 requests the scopes `openid email profile` — no Entra-side API
+permissions need to be granted beyond what a standard app registration
+gets by default.
+
+## Forgejo can use Entra too
+
+If your Forgejo instance should show the same people as f451 without a
+separate identity system, configure Entra as an **authentication source**
+in Forgejo itself (Forgejo admin panel → Authentication Sources → add an
+OAuth2/OIDC source pointed at the same Entra app, or a dedicated one).
+Users then still take the one extra step of linking their Forgejo account
+under **Settings → Connections** in f451 — Entra authenticating both
+systems does not by itself connect them. See
+[[forgejo-identity-provider]] for the setup that removes even that step.