Skip to main content
Most SSO failures come from a handful of causes: a mismatched URL, a missing attribute, a non-email Name ID, an expired certificate, or clock skew. Work top to bottom.

​
Login errors

OpenCX rejected the assertion. Usual causes:
  • Audience / entity ID mismatch: the IdP’s audience doesn’t equal your OpenCX SP Entity ID (exact string, no trailing slash).
  • ACS URL mismatch: the IdP posted to the wrong reply URL. It must equal your OpenCX ACS URL exactly.
  • Unsigned assertion: OpenCX requires a signed response/assertion. Enable signing with your IdP certificate.
The Name ID isn’t the email. If your IdP sends a directory GUID (Entra user.objectid) as Name ID, each login can look like a new identity. Set Name ID format to email and value to the user’s primary email.
Your IdP rotated its signing certificate and OpenCX has the old one. If we loaded a static metadata XML, switch us to your metadata URL so rotations are picked up automatically. Entra ID and AD FS both publish metadata URLs.
The IdP and OpenCX clocks disagree beyond the allowed window. Ensure your IdP host is NTP-synced. This is most common with on-prem AD FS.
The user isn’t assigned to the app (Entra: Users and groups; Okta: Assignments; Google: service OFF for their org unit), or the change hasn’t propagated yet.
  • redirect_uri_mismatch: the registered redirect URI doesn’t exactly match your OpenCX Redirect URI.
  • invalid_client: wrong client ID/secret, or the client secret expired. Rotate it and re-share with OpenCX.

​
Attribute & role problems

First/last name attributes aren’t being sent. Add firstName/lastName (SAML) or grant the profile scope (OIDC). See the attribute reference.
OpenCX isn’t receiving groups, or the group identifiers don’t match your mapping:
  • Confirm the groups claim/attribute is actually emitted (Entra needs a groups claim on the app; Google needs a group mapping).
  • If your IdP sends object IDs (Entra), your OpenCX mapping must use those IDs, not display names.
  • Check the claim isn’t filtered out by a “starts with” / regex rule.
OpenCX grants the highest role among all matched groups. A user in both a viewer group and an admin group becomes an admin. Tighten which groups you emit and map. See role mapping.
JIT doesn’t deprovision: it only blocks the next login. Their current session lasts until it expires. Enable SCIM for real-time deactivation, or ask OpenCX to shorten session lifetime.

​
Before you enforce

Enforcement turns off email + password login for your domain. Run this checklist first. While SSO isn’t self-serve, OpenCX has to reverse enforcement for you, so it’s worth getting right.
1

Every active member logs in via the IdP

Confirm each current OpenCX member exists in your directory, is assigned to the app, and has completed at least one successful SSO login (so JIT has created/linked their account with the right role).
2

Roles are correct

Spot-check that admins are admins and agents are agents after SSO login, and not everyone sitting on the default role.
3

Break-glass account is set

Confirm your break-glass account (billing owner by default) keeps email + password access, its credentials are in your vault, and it has hardware-key MFA. This is your way back in during an IdP outage.
4

Pick a low-traffic window

Cut over when your team is quiet so a surprise doesn’t lock out a live shift. Existing sessions aren’t dropped at enforcement, but new logins must use the IdP.
5

Tell OpenCX to enforce

Give your OpenCX contact the go-ahead. We flip enforcement and confirm the first IdP-only login with you.

​
Locked out?

If your IdP is down and you can’t sign in, use your break-glass account (email + password) to reach the dashboard. If that isn’t available either, contact [email protected] and we can temporarily relax enforcement to restore access.

​
Still stuck?

Gather the failing user’s email, the approximate timestamp, your IdP, and (if you have it) the SAML response or the IdP-side error code, and send it to your OpenCX contact or [email protected]. Those four details resolve the vast majority of cases on the first reply.