Docs, Identity & SSO

Configure Microsoft Entra SSO for Onplana

Step-by-step SAML SSO setup for the IT admin wiring Onplana up to Microsoft Entra ID. Covers the seven configuration steps, the one critical signing-option gotcha that trips every first-time installer, attribute claims, JIT provisioning, MFA-trust behaviour, and the troubleshooting playbook for the handful of errors you might see on first sign-in.

~20 minutes Enterprise plan required SAML 2.0 + OIDC supported

What you'll need before you start

A Microsoft Entra ID tenant with Global Administrator or Application Administrator role on the account doing the setup.
An Onplana org on the Enterprise plan or higher (SSO is gated to ENTERPRISE+).
Admin access to that Onplana org's /integrations page (OWNER or ADMIN role).
The email domains your users sign in with (e.g. acme.com). You'll add them to Onplana's verified-domain allowlist in step 6.

Critical prerequisite, set the signing option

Read this before you start. It's the single most common cause of first-login failure.

Entra's default Signing Option on a new SAML app is Sign SAML response. Onplana rejects responses signed this way with Invalid document signature.

Required setting: in the Entra SAML app, open Single sign-on, SAML Certificates, Edit (pencil), change Signing Option to Sign SAML response and assertion, then save.

Why Onplana doesn't relax this on the SP side: accepting an unsigned assertion inside a signed envelope weakens every customer's posture against XML Signature Wrapping attacks (CVE-2014-3193 class of bugs). Requiring both signatures is the SAML hardening recommendation and matches every major federation profile (eduGAIN, InCommon, etc.). Set it once, you're done.

Setup, seven steps

Create the Onplana SAML enterprise app in Entra

Microsoft Entra admin center, Enterprise applications, New application.
If the Onplana Gallery listing is live, search "Onplana" and pick the Gallery app. Otherwise click Create your own application, name it Onplana SSO, and select Integrate any other application you don't find in the gallery (Non-gallery).
Open the new app and go to Single sign-on, then pick SAML.

Configure Basic SAML Configuration

Click Edit on the Basic SAML Configuration tile and fill in the four fields below. Substitute <tenant-slug> with the calling Onplana org's slug (visible in the Onplana URL bar after sign-in, or in Org Settings, General, Slug).

Field	Value
Identifier (Entity ID)	https://api.onplana.com/api/sso/<tenant-slug>
Reply URL (ACS)	https://api.onplana.com/api/sso/<tenant-slug>/saml/callback
Sign on URL (optional)	https://app.onplana.com/login
Relay State (optional)	Leave blank
Logout URL	Leave blank (Onplana doesn't expose SLO)

These URLs are the exact paths Onplana's SAML SP advertises. The Entity ID deliberately doesn't include a /metadata suffix, the SAML library uses the bare URL as the SP issuer. Save and close the tile.

Set the Signing Option (the critical gotcha)

On the same Single sign-on page, scroll to the SAML Certificatestile. Click the Edit (pencil) icon next to "Signing Option".

Change Signing Option from the Entra default Sign SAML response to Sign SAML response and assertion.
Leave Signing Algorithm at the default (SHA-256).
Click Save.
Back on the Single sign-on page, scroll to the SAML Certificates tile and click Download next to Federation Metadata XML. Save the file, you'll paste pieces of it into Onplana in step 6.

Why this matters: Onplana validates both the SAML Response envelope AND the inner Assertion. Entra's default signs only the Response, which Onplana rejects with Invalid document signature. Onplana requires both because the alternative (relaxing the SP-side check) weakens every customer's posture against XML Signature Wrapping attacks. Get this right once and you're done.

Confirm attribute claims

Onplana's attribute resolver matches the long URIs Entra emits by default, so in most deployments no manual mapping is required. The resolver looks at:

Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (Entra default)
Display name: http://schemas.microsoft.com/identity/claims/displayname (Entra default)
Name identifier: NameID (Entra default; used as fallback when emailaddress is absent)

If you've customised Attributes & Claims on the Entra app and changed any of those URIs, add the short-name override in Onplana under Integrations, SSO, Attribute Map. Onplana accepts either the long URI or the friendly short name (email, displayName, etc.).

Assign users in Entra

On the Onplana SAML app, go to Users and groups, Add user/group.
Pick the users (or Entra groups) you want to give Onplana access.
If your Entra tenant has the Assignment required setting on, only assigned users can sign in. If it's off, any tenant user whose email matches Onplana's verified domains can sign in.

Important: Onplana's verified domains list is the hard gate for first-time sign-in. Before assigning users from yourcompany.com, confirm that domain is on Onplana's SSO settings. If it isn't, the first sign-in returns Email domain is not in this organization's verified SSO domain list.

Paste the metadata into Onplana

In Onplana, open Integrations, SSO tile, SAML. Paste the three values from the Entra federation metadata XML you downloaded in step 3:

IdP Single Sign-On URL, the SingleSignOnService Location attribute from the metadata.
IdP Entity ID (Issuer), the entityID attribute on the root EntityDescriptor element.
IdP X.509 Certificate, the contents of X509Certificate (paste with or without the BEGIN/END markers, Onplana normalises it).

Then configure the org-side knobs:

Default role for new SSO users: MEMBER (recommended) or MANAGER. ADMIN is not available as a default for security reasons, promote individuals from the People page after they sign in.
Verified domains: add the email domains your users sign in with (lowercase). For most installs this is just yourcompany.com.
Just-in-Time provisioning: on by default (first-time SSO sign-in auto-creates the user as the default role). Turn off if you'd rather pre-provision via SCIM or invitation, see the JIT section below.

Click Save, then Enable SSO on the tile.

Test sign-in

In Entra, open the Onplana SAML app, Single sign-on, scroll to Test single sign-on with Onplana, click Test.

Sign in as one of the test users you assigned in step 5.
You should land on https://app.onplana.com/dashboard as that user, with the Onplana org context already set to your tenant.
If the test fails, Entra surfaces a diagnostic panel with the exact SAML error code. Cross-reference with the Troubleshooting section below.

Once the test passes, share the SP-initiated URL with your users:https://app.onplana.com/login. They click "Sign in with SSO", enter their work email, and Onplana redirects to Entra automatically.

Screenshot, Entra Basic SAML Configuration panel

With Identifier, Reply URL, Sign-on URL fields filled in with Onplana URLs.

Screenshot, Entra Signing Option set to "Sign SAML response and assertion"

The SAML Certificates edit dialog showing the required value selected.

Screenshot, Onplana /integrations SSO config form

With IdP Single Sign-On URL, Entity ID, Certificate, default role, and verified domains filled in.

Screenshot, Entra "Test single sign-on" success

The Entra-side test panel showing a green check after a successful SAML round-trip.

Screenshots will land in a follow-up content pass. The text above is sufficient to complete the setup without them.

Optional, OpenID Connect (OIDC)

Onplana supports OIDC as an alternative to SAML. Use OIDC if your org standardises on modern federation, if you'd rather avoid SAML's XML overhead, or if your Entra App registration is already set up.

In Entra, create an App registration (not Enterprise app). Get the Application (client) ID and create a Client Secret under Certificates & secrets.
Add the redirect URI: https://api.onplana.com/api/sso/<tenant-slug>/oidc/callback
In Onplana, Integrations, SSO, OIDC: paste the IdP Entry URL (issuer, typically https://login.microsoftonline.com/<tenant-id>/v2.0), Client ID, and Client Secret.
Save and enable.

Important: Onplana is an OIDC Relying Party (Service Provider), not an Identity Provider. Onplana doesn't expose authorization, token, userinfo, or discovery endpoints. The only URL Entra needs from Onplana is the redirect URI above. If you see references to Onplana endpoints under /authorize or /token, those refer to the MCP server (/mcp), a separate OAuth surface for AI agents.

Multi-factor authentication

When Entra Conditional Access enforces MFA on the Onplana SAML app, Onplana detects this via the SAML AuthnContextClassRef (e.g. multipleauthn) or the OIDC amr claim, and trusts the IdP-asserted MFA as satisfying any local require2FA policy. Your users see exactly one MFA challenge, the one Entra prompts.

If your security posture requires Onplana to enforce a second local MFA on top of Entra MFA (e.g. an Onplana-TOTP independent of Entra), turn off Trust IdP MFA for SSO sessions in Org Settings, Security & Compliance, Controls. Users then get an Onplana TOTP prompt after the SAML round-trip in addition to whatever Entra Conditional Access asked for.

Just-in-Time provisioning

By default, the first SSO sign-in for an unknown email auto-creates the user in Onplana with the SSO config's default role (typically MEMBER). The email domain must be on the verified-domains allowlist, otherwise the sign-in is rejected with a clear error.

If you'd rather require pre-provisioning (via SCIM or manual invitation), turn off the Just-in-Time provisioning toggle in Onplana, Integrations, SSO. Unknown users then see "This organization requires accounts to be provisioned before first SSO sign-in" and are pointed at the org admin. SCIM provisioning is the recommended companion, see the SCIM Entra setup guide for that path.

Troubleshooting

The eight errors below cover roughly 95% of first-install support tickets. If your symptom isn't in the list, the Entra Provisioning Logs panel (or the browser dev-tools network tab for the SAML callback) usually has the exact error code, which is searchable in this list.

I see "Invalid document signature" on first sign-in. What's wrong?

The Entra SAML app's Signing Option is set to the default "Sign SAML response". Onplana requires both the SAML Response AND Assertion to be signed. Fix: Entra admin center, your SAML app, Single sign-on, SAML Certificates, Edit (pencil), Signing Option = "Sign SAML response and assertion", Save. Re-download the federation metadata XML if it changed, paste into Onplana. This is the single most common first-login failure.

Onplana says "Email domain is not in this organization's verified SSO domain list". What does that mean?

Onplana hard-gates SSO sign-in to the email domains an org admin has listed as verified. If your test user has email alice@acme.com, the org must have acme.com on its verified-domains list. Open Onplana, Integrations, SSO, Verified domains. Add the domain (lowercase, e.g. acme.com), save. Verification is admin-attested, not DNS-challenged.

sso_no_email error after the IdP redirect

Entra's SAML response didn't include an email claim. In Entra, your SAML app, Single sign-on, Attributes & Claims, confirm one of the standard URIs is mapped to user.mail (or user.userprincipalname if mail isn't set). Onplana matches the Entra default URIs out of the box, so this only fires when Attribute Claims have been customised and email was dropped.

AADSTS75011 / RequestedAuthnContext mismatch

Resolved in current Onplana builds. The SAML AuthnRequest no longer demands a specific AuthnContextClassRef (Onplana sets disableRequestedAuthnContext = true on the SP-side passport-saml config), so Entra is free to satisfy the request with whatever ClassRef the user's session presents. No admin action needed; if you're still seeing this, the org's Onplana tenant is on an older deployment and re-deploying picks up the fix.

Clock skew error or "NotBefore" / "NotOnOrAfter" complaint

Onplana tolerates up to 30 seconds of clock skew between Entra and the Onplana API host. If your IdP's clock is more than 30 seconds off (rare on Entra; common on misconfigured AD FS), fix the IdP's NTP source. Onplana doesn't expose the 30-second threshold as a per-tenant setting.

Can users sign in with email/password if SSO is configured?

Yes, by default. SSO is an additional sign-in path, not an exclusive one. Onplana does not currently expose a global "force SSO-only" toggle that blocks the email/password path for users whose email matches a verified SSO domain (it is on the roadmap). If you need to enforce SSO-only sign-in today, the operational workaround is to deactivate the password-based user account once the user has signed in via SSO at least once; the SCIM-provisioned (or JIT-created) identity then becomes the only available sign-in path for them. Combine with the "Just-in-Time provisioning" toggle off + SCIM provisioning to lock the surface down further, see the SCIM Entra guide for that path.

Does Onplana support SP-initiated SSO (login from the Onplana login page)?

Yes. From https://app.onplana.com/login, click "Sign in with SSO" and enter your email; if the domain matches a verified SSO domain, Onplana redirects to Entra and returns via the standard SAML ACS. IdP-initiated SSO (start in My Apps in Entra) also works and lands on the dashboard.

Does Onplana support Single Logout (SLO)?

Not in the current release. Onplana doesn't expose a SAML SLO endpoint; leave the Entra app's Logout URL blank. Local sign-out (the Onplana logout button) ends the Onplana session but doesn't propagate to Entra. If you need org-wide forced logout (e.g. after a credential rotation), an OWNER or ADMIN can run the "Force log out all org members" action from Org Settings, which bumps the tokenVersion on every member of that org and invalidates every active session immediately. Individual users can also self-revoke from Settings, Security, Logout all devices to sign themselves out of every device they own.

Next steps

Now that SSO is wired up, the natural follow-on is automated user provisioning via SCIM. Once SCIM is configured, Entra creates / updates / deactivates Onplana users automatically as you adjust group memberships and HR data, no admin work per user.

SCIM Provisioning with Microsoft Entra

The companion setup guide. Generates the SCIM token, paste it into Entra, configure attribute mappings, assign users.

Continue to SCIM setup

Security at Onplana

Encryption, audit logging, IP allowlisting, session policy, data residency. The full security posture in one page.

Read security overview

This page is the canonical SSO-Entra setup reference linked from Onplana's Microsoft Entra Application Gallery listing. If you found an error or want a section expanded, mail hello@onplana.com. Last verified against Onplana production: 2026-05-21.