Microsoft Entra ID

Microsoft Entra ID#

Sign in with accounts from a Microsoft Entra ID tenant, formerly Azure AD.

Entra is a standard OpenID Connect provider, so this uses the oidc-generic driver.

Warning

Provider-side steps are not verified. The Plone side below is read from this package's source and is accurate. The Entra portal steps have not been walked through against a live tenant. Follow Microsoft's own OpenID Connect documentation for the portal, and use the tables here for Plone.

1. What you need from Entra#

Issuer

https://login.microsoftonline.com/<tenant-id>/v2.0

Client ID

the application (client) ID

Client secret

from Certificates & secrets

Confirm the issuer before configuring it:

curl -s https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration | jq .issuer

Register the redirect URI on the app registration, as a Web platform:

https://www.example.com/login-identity

2. Add the provider#

  1. Open the Identity providers control panel.

  2. Add a provider and choose OpenID Connect (oidc-generic).

  3. On the Settings tab:

    Field

    Value

    Title

    your organization's name

    Issuer

    from step 1, including the /v2.0

    Client ID

    from step 1

    Client secret

    from step 1

    Scope

    leave empty for openid email profile

  4. Save, then Test connection.

3. Email verification—read this before switching anything on#

Warning

Entra does not send email_verified.

An absent claim is not a true, so this package treats every address from Entra as unverified. Turning on Trust this provider's email verification changes nothing, and turning on Attach to an existing account with the same verified email then never fires, because there is no verified address to match on.

The symptom is silence: sign-in works and linking never happens.

If you need accounts linked by address for an Entra tenant, that is a decision to make deliberately and not one this package can make from the claims. The safe arrangement is to turn off account creation and add the accounts yourself, so each match is a human decision.

4. Groups need configuration in the app manifest#

Entra sends no groups claim until you ask for one, in the app registration's Token configuration or in the manifest's groupMembershipClaims.

Two things to know once you do:

  • Group ids arrive, not names. Entra sends object GUIDs by default, so the left-hand side of your group map is a GUID unless the tenant is configured to emit group names.

  • Large group counts are truncated. Past a limit Entra replaces the claim with a link to fetch groups from Microsoft Graph, which this package does not follow. A user in many groups may arrive with none.

Set Groups arrive in the claim to groups once it is emitted, and map the ids you care about—see How to map provider groups.

Verify#

  1. /login shows the button, and signing in returns you signed in.

  2. /identities lists the identity.

  3. The audit log has an authenticated entry.

  4. If you configured groups, a mapped group appears in the user's membership.

Known quirks#

  • No email_verified. See step 3. This is the one that surprises people.

  • The /v2.0 suffix is part of the issuer. Leaving it off gives you the v1 endpoint, whose tokens differ.

  • Group claims are GUIDs, and are truncated in bulk. See step 4.

Contents