admin-guide/entra-id/index.md

id	title	description	tags	lang
entra-id	Microsoft Entra ID	Registering an app in Entra and pointing f451's OIDC configuration at it, step by step.	admin auth entra	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.