Skip to main content

​
Troubleshooting: SAML SSO and SCIM setup failures

This runbook covers setup-time failures when you enroll SAML SSO or wire SCIM provisioning — the misconfiguration class that blocks enrollment before any real user signs in. It complements the enrollment guide, which is the happy path; this page is what you reach for when the happy path breaks. SAML and SCIM are per-organization, tenant-owned controls: an owner writes the SAML configuration under Settings → Security over the GET/PATCH pair on /api/v1/settings/saml, and SCIM runs against the org-scoped base URL /scim/v2/{orgSlug} with a dedicated Bearer token minted under Settings → SCIM. The conceptual model is on Identity federation: SAML and SCIM.

​
Symptom table

Match the behavior you see to the cause column before changing anything:
The [REDACTED] mask is the load-bearing difference between a read failure and a healthy config: GET /api/v1/settings/sso and the settings read never return the stored certificate, by design. If the mask flips back to [REDACTED] after your re-paste, that means the write landed. Diagnose further only if login still fails.

​
Causes by category

​
Certificate and metadata problems

  • PEM whitespace or stripped headers. The certificate field expects the X.509 PEM value. Pasting from some IdP consoles carries smart quotes, line-wrap whitespace, or drops the BEGIN/END CERTIFICATE markers. Always re-pull the metadata XML (Okta: “Identity Provider metadata” link; Entra ID: “Federation metadata document”) and copy the <ds:X509Certificate> value from inside it rather than re-copying from a rendered certificate blade.
  • Algorithm mismatch: SHA-1 vs SHA-256. A stale Okta/Entra app that signs with SHA-1 while your validation expects SHA-256 (or the reverse) fails on every assertion with a signature error. Align the algorithms on both sides; SHA-256 is the expected default.
  • Clock skew vs NotBefore/NotOnOrAfter. SAML assertions carry a validity window. If your IdP’s clock drifts, assertions arrive outside their window and the ACS rejects them. Sync the IdP-side clock (NTP) before you re-test; this is the only cause in this list that fails even with a perfect certificate.

​
Permission and write-refusal problems

  • Non-owner 403. PATCH /api/v1/settings/saml (and the Settings → Security SAML form) are owner-only writes. Admins can GET the config and run the test-connection probe, but cannot save. The 403 is deterministic — retrying from the same non-owner session returns the same refusal.
  • Wrong orgSlug in the SCIM path. The base URL is /scim/v2/{orgSlug} — the slug is the exact org-scoped value shown under Settings → SCIM, not a tenant ID and not a bare org name. A 404 or 422 from every push means the slug segment is wrong.
  • Missing or wrong Bearer token. SCIM requests authenticate with the dedicated token minted under Settings → SCIM, sent as Authorization: Bearer <token>. A 401 on every push means the header is missing or the token was rotated and the IdP still sends the old one.

​
Fix sequence

Work in this order. Stop at the first step that clears the failure.
  1. Re-pull the IdP metadata XML. In Okta, open the app’s Sign On tab and copy the “Identity Provider metadata” link; in Entra ID, open the enterprise application’s Single sign-on blade and download the “Federation metadata document”. Extract the signing certificate from the <ds:X509Certificate> element — this avoids the whitespace/header corruption that rendered certificate screens introduce.
  2. Re-paste in Settings → Security. Have an owner paste the fresh certificate into the SAML configuration. The read-back shows [REDACTED] — that’s the mask, not a failed write.
  3. Run a fresh SP-initiated loop. Open /auth/saml/{orgSlug}/login, let it 302 to the IdP, and confirm the callback lands a session. A clean SP-initiated loop is the proof the fix landed — not the read response.
  4. Break-glass owner. If enforced locked the only owner out, a second owner opens the dashboard via SSO and flips enforced: false to re-open password sign-in. Keep enforcement off until the loop above passes for your team and a second owner can still break-glass.
  5. Flip to enforced last. Re-stage enforced: true only after the SP-initiated loop passes for a non-owner test member. Enforcement is the final step, not a debugging step.
Never flip enforced: true while debugging. If the loop fails under enforcement, every member — including other owners — loses the fallback sign-in path and the break-glass route narrows to a support escalation.

​
SCIM-specific fix order

  1. Verify the base URL exactly as shown under Settings → SCIM — the orgSlug segment is org-scoped and case-sensitive.
  2. Verify the Bearer token is the current one from Settings → SCIM; rotate it there if you suspect the IdP holds a stale copy, then update the IdP’s connection settings.
  3. Trigger a manual push from the IdP (Okta: Push now; Entra: Provision on demand) and read the IdP-side error. The IdP error string is the fastest signal: 401 → token/header, 404/422 → orgSlug, 400 → schema or attribute mapping.

​
What to send support

If the fix sequence above still fails, open a ticket with:
  • Your organization slug and tenant ID (Settings → Organization).
  • The exact SAML failure: the ACS 401 response, the IdP error string, or the SCIM status code — plus the request_id from the meta block of an API response when you have one.
  • The IdP vendor and app type (Okta / Entra ID / other SAML 2.0 IdP) so the support engineer can compare against the enrollment guide’s mapping table.
Never include the certificate, the SCIM Bearer token, or a session JWT in the ticket.

​
See also

  • Enroll SAML SSO — the happy-path walkthrough: metadata probe, writing the config, enforcement, and the common-failures table.
  • Identity federation: SAML and SCIM — what gets federated, the create → update → deactivate → deprovision lifecycle, and the tenant-ownership model.
  • SSO / SCIM FAQ — conceptual answers: what SSO, SP-initiated vs IdP-initiated SAML, and SCIM provisioning each do, and how the staged enabled → enforced rollout works.
  • Authentication, key mode, and IP allowlist — the sibling runbook for runtime SSO rejection codes on the login path.