> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting SSO

> Diagnose common OpenCX SSO problems, assertion and attribute errors, Name ID mismatches, clock skew, certificate rotation, role-mapping surprises, plus the pre-cutover checklist before you enforce.

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

<AccordionGroup>
  <Accordion title="Redirected to the IdP, then bounced back to login" icon="arrows-rotate">
    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.
  </Accordion>

  <Accordion title="Duplicate accounts appear on re-login" icon="user-group">
    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.
  </Accordion>

  <Accordion title="'Invalid signature' or 'certificate' errors" icon="certificate">
    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.
  </Accordion>

  <Accordion title="'Response too old' / 'not yet valid' / clock skew" icon="clock">
    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**.
  </Accordion>

  <Accordion title="User denied at the IdP" icon="ban">
    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.
  </Accordion>

  <Accordion title="OIDC: redirect_uri_mismatch / invalid_client" icon="fingerprint">
    * `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.
  </Accordion>
</AccordionGroup>

## Attribute & role problems

<AccordionGroup>
  <Accordion title="Members' names show blank" icon="user-pen">
    First/last name attributes aren't being sent. Add `firstName`/`lastName` (SAML) or grant the `profile` scope (OIDC). See the [attribute reference](/security/sso/scim#attribute-reference).
  </Accordion>

  <Accordion title="Everyone lands as the default role" icon="user-shield">
    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.
  </Accordion>

  <Accordion title="A user has more access than expected" icon="triangle-exclamation">
    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](/security/sso/scim#role-mapping).
  </Accordion>

  <Accordion title="Disabled a user, but they're still in OpenCX" icon="user-slash">
    **JIT doesn't deprovision**: it only blocks the next login. Their current session lasts until it expires. Enable [SCIM](/security/sso/scim#scim-2-0) for real-time deactivation, or ask OpenCX to shorten session lifetime.
  </Accordion>
</AccordionGroup>

## 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.

<Steps>
  <Step title="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).
  </Step>

  <Step title="Roles are correct">
    Spot-check that admins are admins and agents are agents after SSO login, and not everyone sitting on the default role.
  </Step>

  <Step title="Break-glass account is set">
    Confirm your [break-glass account](/security/sso/overview#enforcement-break-glass) (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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Tell OpenCX to enforce">
    Give your OpenCX contact the go-ahead. We flip enforcement and confirm the first IdP-only login with you.
  </Step>
</Steps>

## Locked out?

<Warning>
  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 [support@open.cx](mailto:support@open.cx) and we can temporarily relax enforcement to restore access.
</Warning>

## 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 [support@open.cx](mailto:support@open.cx). Those four details resolve the vast majority of cases on the first reply.

## Related

* [SSO overview](/security/sso/overview)
* [Provisioning & role mapping](/security/sso/scim)