77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
---
|
|
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.
|