Craft CMS OpenID Connect login with Microsoft Entra ID

What you will need

• A Craft 5 site served over HTTPS. The plugin refuses an OIDC redirect URI that is not https, with no loopback exception and no setting to relax it.
• An administrator account in Craft that you can still sign in to with a password, and enough rights in the tenant to register an application and grant its permissions.
• A single-tenant issuer. The plugin compares the issuer byte for byte in two places — against the discovery document's issuer field and against the iss claim of every id token — so a multi-tenant endpoint whose discovery document returns a templated issuer (one containing a {tenantid}-style placeholder) can never match.

Step 1 — Copy the redirect URI this site answers on

In Craft, open Settings → Plugins → Keyway SSO and set Protocol to OpenID Connect. Do not fill in the provider fields yet: first copy the read-only Redirect URI this site answers on. It deliberately carries no control panel prefix, because that prefix can be renamed at any time and a redirect URI the provider no longer recognises stops every login.

Check the shape of that address before you register it. If it contains index.php?p=, this site generates URLs with the script name in them — turn on Craft's omitScriptNameInUrls and re-read the value. Some providers refuse a redirect URI containing a query string; whether Entra ID accepts such a URI is not verified, so register the clean form and avoid the question. Nothing is saved yet, and while the configuration is incomplete the SSO button stays off the login screen — that is normal.

Step 2 — Register the application

[portal] The path has changed several times; at the time of writing it is broadly Identity → Applications → App registrations → New registration, but navigate by what you are trying to achieve rather than by those names. What you need to end up with:

1. An app registration restricted to this organizational directory only (single tenant), for the issuer reason above.
2. A redirect URI of platform type "Web", set to exactly the address from Step 1 — character for character, including the scheme, any trailing element and letter case. Do not enable the implicit grant or hybrid options, and leave the response coming back as a redirect with a query string: this plugin uses the authorization code flow with PKCE and its callback reads query parameters only.
3. A client secret, unless you deliberately want a public client. A secret makes it a confidential client; an empty Client secret field makes it a public one. PKCE (S256) is mandatory in both cases — it is a constant in the code, not a setting. [portal] Secrets live under the registration's Certificates & secrets; copy the value immediately, it is shown once.
4. Delegated permissions matching the scopes you will request: at minimum openid, profile and email. This matters more than it looks — the default attribute mapping requires an email value, and an id token issued without the email scope (or for an account with no mail attribute) fails the login with attributes_rejected.
5. Group claims, if you intend to map groups. [portal] They are configured on the registration's token configuration / optional claims. Read Step 4 first: the format you choose decides whether your mapping table holds readable names or GUIDs.

What you do not need to configure: signing algorithms (the plugin accepts RS256 and ES256 only, and Entra's published id token signing algorithm is within that set), a PKCE method, or a logout URL — the OIDC side of this plugin has no logout support.

Step 3 — Paste the values back into Craft

Issuer. Do not type this from memory and do not copy it out of a blog post. Fetch your tenant's OpenID configuration document and copy the value of its issuer field verbatim:

curl -s https://login.microsoftonline.com/<your-tenant-id>/v2.0/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"'

The plugin appends /.well-known/openid-configuration to whatever you enter, fetches that document, and refuses to go any further unless the document's own issuer equals your setting byte for byte — no trailing-slash forgiveness, no case folding. Run that same command from the web server, not only from your laptop: if the server cannot reach Microsoft, every login fails at start_failed / discovery_failed before the user ever sees Microsoft's page.

Client ID. The application (client) ID of the registration. The plugin requires it to appear in the id token's aud; when a token carries several audiences it additionally requires azp to name this client.

Client secret. Store it as an environment variable, not as a literal: put KEYWAY_OIDC_SECRET=… in the server's environment and write $KEYWAY_OIDC_SECRET in the field. If the variable is missing or empty, the settings screen says so by name and single sign-on stays off — it is not treated as "no secret", because that would silently downgrade a confidential client to a public one. Leave the field empty only if you genuinely registered a public client.

Redirect URI. The same characters you registered. The screen compares what you typed against what this site actually answers on and comments underneath if they reach the same endpoint but are written differently — take that comment seriously, both sides compare this value character for character.

Scopes. One per line; the shipped default is openid, profile, email. openid is added automatically whether you list it or not. Clearing the box restores the three defaults, and scopes containing a space are dropped silently.

Fetch userinfo is off by default. Turn it on only if a claim you need is missing from the id token: the userinfo sub must equal the id token's sub or the login is refused with subject_mismatch, id token claims win on conflict, and a signed userinfo response (application/jwt) is refused outright. Clock skew defaults to 60 seconds and caps at 120; an id token is refused once it is more than 300 seconds old whatever this is set to.

Step 4 — Attributes and groups

Fill the table in explicitly: email → email with Required on, given_name → firstName, family_name → lastName. Targets may be email, username, firstName, lastName, fullName or field:<handle>; nothing else is writable. Confirm the claim names against your own tenant rather than against this page — after the first attempt, the row's Details → Attributes received lists exactly what arrived.

Groups. Microsoft's group claim commonly carries group object IDs (GUIDs), not group names, and this plugin does not resolve them — it matches the strings it receives and nothing more. So your rules will contain patterns like 9a8b7c6d-1234-4321-abcd-0123456789ab, Prefix and Suffix matching is useless against them (use Exact), the table becomes unreadable to anyone who did not build it, and a wrong GUID in Admin rules grants Craft admin to the wrong people. [portal] Entra can be configured to emit group names instead of object IDs for groups synchronised from on-premises Active Directory; whether that applies to your directory is not something this guide can verify — check what actually arrives, under Details → Mapped to → matchedIdpGroups / unmatchedIdpGroups. More: group mapping.

How OIDC differs from SAML in this plugin

Testing, and the four codes you are most likely to meet

Test in a private window, leaving your administrator session signed in elsewhere. Then look at the diagnostics row even after a success: jit_create means a new Craft account was created, update_on_login that an existing one matched, existing_unchanged that nothing was changed. Watch for a blue Notice row too — provisioning_incomplete means the login worked but part of the configuration could not be applied (a Craft group handle that does not exist, a custom field missing from the user field layout), and nothing else in Craft will ever tell you that.

The person signing in sees one deliberately vague sentence whatever the cause; the real reason is always on the diagnostics screen.

Known limits with Entra ID

• This guide is not verified against a live tenant. Treat every [portal] instruction as a description of intent, not a confirmed click path.
• No logout support over OIDC, in either direction. Signing out of Craft does not sign the user out of Microsoft, and signing out at Microsoft does not end the Craft session. The plugin's logout endpoint is SAML-only and is dead on an install configured for OIDC.
• Single-tenant issuers only, for the byte-for-byte reason above.
• Entra's sub is a pairwise identifier: stable for a given user in a given app registration, and a different value in a different one. Moving this site to a new registration, or recreating it, changes sub for everybody, and every account single sign-on created is then refused with linking_disabled until an administrator clears the stale records. It is not a reason to avoid doing it; it is a reason to plan it.
• Group claims usually arrive as GUIDs. There is no name resolution here.
• The response must come back on the query string, and a registration that POSTs it breaks every login outside the plugin, with no diagnostics row.
• PKCE is mandatory and not configurable, so is the signing-algorithm allow list, the time checks always run, and signed userinfo responses are refused.
• Nothing here is a statement about support, certification or any commercial relationship with Microsoft. It is a technical description of how this plugin's OIDC reader behaves.