Craft CMS SAML SSO: signing in to the control panel with SAML 2.0

The three values, and where they come from

From the provider you need three things in return: its IdP entity ID (the issuer it stamps on assertions), its IdP SSO URL (where the browser is sent to log in) and its IdP signing certificate. The certificate has to be the full X.509 certificate, PEM or bare base64 — a fingerprint is rejected, because a fingerprint proves which certificate the message carried, not which one you trust.

The order that actually works

The settings screen is validated as a whole. With Protocol set to SAML 2.0, a save is rejected until IdP entity ID, IdP signing certificate, IdP SSO URL, SP entity ID and ACS URL are all present and well-formed — and a rejected save stores nothing. So:

1. Open Settings → Plugins → Keyway SSO, set Protocol to SAML 2.0, and copy the ACS URL and the site URL. Both are readable before you save anything, because the plugin builds them from its own registered routes.
2. Create the application at your provider and give it those two values.
3. Come back with the provider's three values and save the complete configuration.
4. Only now, if your console wants it, hand over Download metadata or the Metadata URL — and re-check the application afterwards.
5. Map attributes and groups, then test in a private window and read the diagnostics row.

Note what the document does not carry, so nothing surprises you: no KeyDescriptor (the plugin has no field for an SP certificate), a NameIDFormat of unspecified, AuthnRequestsSigned="false", and no SingleLogoutService until logout is configured.

What the signature has to cover

• The assertion must be signed, and that check cannot be turned off. There is no setting to accept an unsigned one.
• The signature must cover the assertion that was parsed. A missing or duplicate assertion ID, no single ds:Signature child, a Reference pointing elsewhere or a missing enveloped-signature transform is refused as signature_coverage. If you see it, something is re-wrapping the response — investigate that rather than relaxing anything, because nothing here can be relaxed.
• Authentication requests are sent unsigned. A provider configured to require a signed request will reject every login; that switch lives at the provider.
• Time checks cannot be turned off — only their tolerance, up to 120 seconds. A login also has five minutes between pressing the SSO button and the assertion coming back.
• Encrypted assertions are supported through SP private key, but there is no field for an SP certificate, so the metadata carries no key material: if you encrypt assertions, the matching certificate has to reach your provider by another route.
• An XML DOCTYPE declaration is refused outright, as an entity-expansion defence.

Two rules that bite later, not on day one

The Name ID has to be stable. Accounts the plugin creates are recognised on later logins by account, issuer and subject — the NameID. Use persistent or emailAddress. transient is a fresh value on every login by definition, so every second login of every user is refused with linking_disabled. The plugin never reads the format attribute, so this is a configuration rule, not a check you can fail, and there is no error message pointing at it.

Logins must start on the Craft side. The plugin requires its own RelayState and a matching InResponseTo, so an assertion belonging to no login of ours is refused as unsolicited_response. In practice: the dashboard tile for this application will not sign anybody in. Send people to the Craft login screen and let them press the SSO button.

Single Logout: SAML only, one way, opt-in — and not with Okta

Single Logout (SAML only, one direction, opt-in: it needs your provider's logout URL and an SP private key before it does anything): when your identity provider sends a signed SAML LogoutRequest, the plugin ends the matching Craft session. Signing out of Craft does not end the session at your identity provider, and Okta will not send such a request after an ordinary Okta sign-out — so with Okta as your only provider, plan on single sign-on, not single logout. Verified end to end against Keycloak 26.0; OpenID Connect has no logout support.

Mechanically, on a SAML installation that opts in: the endpoint is /actions/keyway-sso/sso/slo, HTTP-Redirect binding only, and it stays shut until IdP single logout URL and an SP private key are both set — until then it refuses every message and the metadata document deliberately advertises no SingleLogoutService, because advertising one would make every provider that reads the document send logout requests to an address that answers nothing. A request is honoured only when its subject matches the session in the browser that carried it; a mismatch ends nothing and is answered UnknownPrincipal, which is also what a browser with no session gets.

What to check when it fails

Open Settings → Plugins → Keyway SSO and read the warnings at the top, then press Open sign-in diagnostics. Every attempt is a row with its stage, outcome, a machine reason code and a Details panel holding the attributes that arrived, what they mapped to and the decision taken. The person signing in only ever sees one vague sentence — that is deliberate, so that the login endpoint cannot be used to tell an existing account from a missing one.

The full table, including the codes that appear only on unusual installations, is on when single sign-on does not sign anybody in. Provider specifics: Okta, Keycloak.