Single sign-on with Microsoft Entra ID

This guide connects BROKA to Microsoft Entra ID over OpenID Connect: an app registration in Entra, a provider in BROKA, and the groups that put people in BROKA's teams. What each BROKA setting does is described on Single sign-on.

In BROKA, first

In Settings ▸ Security ▸ Single sign-on, choose New provider, then OpenID Connect and Microsoft Entra ID, and give it the name people will see on the sign-in page and a Slug, part of the address Entra sends people back to. The sheet's Give your identity provider these section then shows the Redirect URI Entra needs; switch on Also sign out of at the foot of the sheet if BROKA should also sign people out of Microsoft, and the section shows the Sign-out redirect URI as well. Keep the sheet open.

In Microsoft Entra ID

1. In the Microsoft Entra admin center, open App registrations ▸ New registration. Name it; under Supported account types, choose Single tenant; under Redirect URI, choose Web and paste BROKA's Redirect URI. As the form says, registering accepts the Microsoft Platform Policies.
2. From the registration's Overview, note the Application (client) ID and the Directory (tenant) ID.
3. Under Certificates & secrets ▸ Client secrets, add a New client secret and copy its Value — not its secret ID — at once: Entra shows it only then. Note when it expires.
4. Under Token configuration, Add groups claim: choose Groups assigned to the application, or Security groups, and Group ID for the ID token. Groups can be assigned to an application only with Microsoft Entra ID P1 or P2, and Groups assigned to the application sends only the assigned groups the person is a direct member of, never one they belong to through another group. Without P1 or P2, or where people are in BROKA's groups through other groups, choose Security groups.
5. Under Token configuration, Add optional claim for the ID token: email, xms_edov and verified_primary_email — what BROKA reads to know an address is verified. Entra offers to turn on the Microsoft Graph email permission these claims need: turn it on.
6. If BROKA should also sign people out of Microsoft, add BROKA's Sign-out redirect URI under Authentication as a second Web redirect URI.
7. To let in only the people and groups you choose, open the application under Enterprise applications, set Assignment required to Yes in its Properties, and assign them under Users and groups — yourself included, so that you can run the test. Assigning groups, rather than people one by one, needs P1 or P2.

Back in BROKA

• Issuer URL: https://login.microsoftonline.com/ followed by your Directory (tenant) ID and /v2.0.
• Client ID: the Application (client) ID.
• Client secret: the value from step 3, and its expiry date under Expires (optional).
• Scopes: the default, openid profile email.

BROKA identifies each person by their object ID in your tenant, which Entra never changes and which stays the same if the application is ever registered again — so the links between people and their BROKA accounts survive it.

Save, then Test sign-in. The result shows what Entra sent — the e-mail address and whether BROKA counts it as verified, the tenant, and the group IDs. When it has passed, map the groups under Group mappings, and Enable the provider.

Groups

Entra sends group object IDs. Map those: Entra never reuses an ID, while two groups can share a name.

A token carries at most 200 groups. Beyond that, Entra leaves the groups out and says so, and BROKA then changes no membership and creates no account for that sign-in. Groups assigned to the application keeps the list to the groups that matter to BROKA; with Security groups, a person in more than 200 groups arrives with none.

Entra sends no groups at all for someone in none of the groups the claim selects, and a sign-in without groups changes no membership in BROKA. So removing someone from their last mapped group in Entra leaves their BROKA teams as they are: remove the mapping, or disable the account in BROKA.

Accounts

Entra sends no email_verified, and an address in its email claim alone proves nothing. BROKA counts an Entra address as verified only when xms_edov says the owner of its domain was verified, or when verified_primary_email holds the same address — and only on a provider with allowed domains set. That is what Link existing accounts by e-mail and Create an account at first sign-in rely on. Entra sends an address only for a person whose Entra profile has one: give people their address there, the person you test with included.

An application registered for accounts in any organisation's directory is accepted only with the provider's Allowed tenants set, by tenant ID, and then only for people signing in from one of them. For an application registered for your tenant alone, leave the list empty.

A second factor

Entra's tokens carry no claim saying that a second factor was used, so BROKA records every Entra sign-in as made without one, even when the person used one at Microsoft. Require a second factor in Entra itself, with Conditional Access or the security defaults.

Signing out

With Also sign out of Entra switched on, signing out of BROKA signs the person out of Microsoft in that browser, and Microsoft sends them back to BROKA's sign-in page — the address registered in step 6.