Single sign-on (SSO)

Let your team sign in to OpenCX through your own identity provider, using SAML 2.0 or OpenID Connect.

​

Overview

We support most identity providers (Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud, Auth0, Keycloak, AD FS, etc.) over SAML 2.0 or OIDC. Members sign in by clicking Sign in with SSO on platform.open.cx and entering their work email — OpenCX matches the domain to your provider and redirects to your IdP. Each provider is bound to one email domain, verified with a DNS record before sign-ins work. Working with multiple domains? Add a provider per domain. Directory sync sits on top: SCIM provisioning creates accounts when you assign users in your IdP and cuts off access when you unassign them, instead of waiting for a sign-in attempt.

​

Configure

1. Navigate to Settings → Security and click Add provider.
2. Pick SAML or OIDC and fill in the form. For SAML you’ll paste your IdP’s metadata XML and its entity ID; for OIDC, the issuer URL, client ID, and client secret. Every provider needs the email domain your team signs in with.
3. OpenCX generates your provider’s IdP-facing values at creation, so create the app in your IdP with placeholder URLs first, then replace them with the real values shown on the provider card — Reply URL (ACS) and Identifier (Entity ID) for SAML, or Redirect URI for OIDC. Each value has a copy button.
4. Click Set up DNS on the provider card, publish the TXT record it shows, then click Verify domain. Sign-ins for the domain are rejected until this passes — see Domain verification.

​

Okta

• Okta documentation
• In the Okta Admin console, navigate to Applications → Create App Integration → SAML 2.0 and name the app.
• Set Name ID format to EmailAddress and Application username to Email — OpenCX identifies members by email.
• From the app’s Sign On tab, open View IdP metadata and paste the XML into OpenCX. The metadata’s entityID is your IdP entity ID.
• Enter OpenCX’s Reply URL (ACS) as the Single sign-on URL in Okta, and Identifier (Entity ID) as the Audience URI, then assign users to the app.

​

Microsoft Entra ID

Entra works over both protocols: SAML via an enterprise application, or OIDC via an app registration. It works even if your email is hosted elsewhere (e.g. Google Workspace). SAML — Entra ID documentation

• From Microsoft Entra ID, select Enterprise Applications → New application → Create your own application (non-gallery), then Single sign-on → SAML.
• Edit Attributes & Claims and set the Unique User Identifier (Name ID) to Email address format, source user.mail. If user.mail is empty (cloud-only users without a mailbox), fill the user’s Mail attribute — or use user.userprincipalname, but only when all members’ UPNs are on your email domain (the default UPN breaks guest users, see FAQ).
• Download the Federation Metadata XML (SAML Certificates section) and paste its contents into OpenCX. Your IdP entity ID is the Microsoft Entra Identifier (https://sts.windows.net/<tenant-id>/), also the metadata’s entityID.
• Enter OpenCX’s values in Basic SAML Configuration — the field names match the provider card.
• Assign users or groups under Users and groups — unassigned users get AADSTS50105 at sign-in.

OIDC

• From App registrations → New registration, create a single-tenant app. Under Authentication → Add a platform → Web, set OpenCX’s Redirect URI from the provider card. Leave both implicit-grant checkboxes unchecked — OpenCX uses the authorization-code flow.
• Under Certificates & secrets, create a client secret and copy its Value (shown only once) — not the Secret ID.
• Your issuer URL is https://login.microsoftonline.com/<tenant-id>/v2.0.
• Under Token configuration, add the optional email claim to the ID token — the user’s email must be on your verified domain (the guest-user caveat above applies here too).

​

Google Workspace

• Google documentation
• In the Admin console, navigate to Apps → Web and mobile apps → Add app → Add custom SAML app.
• Download the metadata on the Google Identity Provider details step and paste its contents into OpenCX. Set Name ID to Primary email, format EMAIL.
• Enter OpenCX’s Reply URL (ACS) as the ACS URL and Identifier (Entity ID) as the Entity ID.
• Turn the app ON for the organizational units that need access — Google apps default to OFF, and changes can take a while to propagate.

​

Other SAML providers

• Any standards-compliant SAML 2.0 IdP works — OneLogin, JumpCloud, Ping, Duo, Auth0, on-prem AD FS. Export the app’s metadata XML and paste it into OpenCX.
• The Name ID must be the user’s email (format emailAddress), and the response must be signed — unsigned assertions are rejected. Sign with SHA-256 or better: old AD FS installs default to SHA-1, so change the relying party trust’s secure hash algorithm.
• Keep the IdP host NTP-synced: assertions outside their timestamp validity window are rejected.
• OpenCX’s Identifier (Entity ID) URL serves standard SP metadata XML — IdPs that import SP metadata can consume it directly.

​

OIDC providers

• Create a web application (confidential client) using the authorization-code grant, with the openid, email, and profile scopes. The ID token must carry an email claim.
• The issuer URL must be HTTPS and publicly reachable; OpenCX validates its discovery document ({issuer}/.well-known/openid-configuration) when you add the provider. A Discovery endpoint field is available if yours lives elsewhere.
• Enter OpenCX’s Redirect URI as the client’s allowed callback URL — it must match exactly.
• Client secrets expire — note the date, and re-add the provider with a fresh secret before it lapses.

​

Just-in-time provisioning

When someone signs in through your IdP for the first time, OpenCX creates their account and adds them to your organization. Sign-ins with an email that isn’t on your verified domain are rejected, with the reason shown on the sign-in page. Set during account creation:

• Email: the SAML Name ID or OIDC email claim. This is the identity key — OpenCX matches sign-ins to members by email.
• Name: taken from your IdP’s name attributes or the name claim.
• Role: the SSO Member role, auto-created in your organization the first time it’s needed. It grants read-only access to conversations and nothing else.

Later sign-ins never update the member — in particular, SSO never changes roles. To give someone more access, assign a role at Settings → Teammates; to change what all future SSO users get, edit the SSO Member role at Settings → Roles.

​

Domain verification

Each provider shows a DNS challenge under Set up DNS on its card: Publish the record in your DNS zone, then click Verify domain. The token is stable for the life of the provider, so leave the record in place and retry while DNS propagates. Verification is what stops anyone else from wiring SSO for a domain they don’t own.

​

SCIM provisioning

SCIM 2.0 keeps OpenCX in sync with your directory: assigning a user in your IdP creates their OpenCX account, and unassigning or disabling one revokes their access on the next sync cycle. It complements SSO rather than replacing it — sign-in still runs through your provider. SCIM requires an SSO provider with a DNS-verified domain on the same organization. It never creates users on a domain you haven’t verified — those attempts fail with scim_domain_not_verified in your IdP’s provisioning log.

1. Navigate to Settings → Security, find SCIM provisioning, and click Set up SCIM.
2. Copy the Tenant URL (https://api.open.cx/backend/auth/scim/v2) and the secret token.
3. Paste both into your IdP’s provisioning configuration — see Entra ID provisioning below.

​

What syncs

Users only. Group and role sync aren’t supported — roles are assigned in OpenCX. Create and assign — OpenCX creates the account with its email pre-verified and adds it to your organization with the SSO Member role, the same least-privilege default that SSO sign-in grants. If the person already exists — invited earlier, or signed in through SSO before — SCIM links to that account instead of creating a second one, and leaves their existing roles alone. SCIM never downgrades anyone. Upgrade access per person at Settings → Teammates. Deactivate (active: false) — unassigning or disabling the user in your IdP bans them, revokes every live session immediately, and blocks sign-in. Organization membership and roles are preserved, so flipping them back to active: true restores the person exactly as they were. Delete — a hard delete removes the person from your workspace: membership and the SCIM link go away and sessions are revoked, but their conversation history is preserved. Delete doesn’t ban — deactivation is the tool for blocking access, and Entra always deactivates before it deletes.

​

Entra ID provisioning

• Entra ID documentation
• From Enterprise applications, open the same app you use for SSO — or create a new non-gallery app — then select Provisioning → New configuration.
• Set the mode to Automatic, paste the Tenant URL and Secret Token from the OpenCX dashboard, and click Test Connection.
• Under Mappings, the defaults work: userName must map to the user’s email (userPrincipalName), and externalId to objectId. Provision Users only — disable the Groups mapping, which OpenCX doesn’t support.
• Set Scope to Sync only assigned users and groups, then assign the users and groups to provision under Users and groups.
• Turn provisioning On. Entra’s sync cycle runs roughly every 40 minutes, so creates and deactivations land on that cadence — offboarding takes effect at sync time rather than waiting for the user’s next sign-in attempt, as it does with SSO alone.

​

Okta provisioning

Okta takes the same two values: in the app’s Provisioning tab, set the SCIM connector base URL to the Tenant URL and Authentication Mode to HTTP Header, with the OpenCX token as the bearer token.

​

Offboarding

With SCIM connected, disabling or unassigning a user in your IdP revokes their OpenCX sessions and cuts off their access on the next sync cycle — no dashboard step needed. Without SCIM, disabling a user in your IdP only blocks their next SSO sign-in. It doesn’t end active OpenCX sessions or remove their membership — for immediate, complete removal, also remove them at Settings → Teammates.

​

FAQ

Still stuck? Send the failing user’s email, the approximate time, your IdP, and any IdP-side error code to [email protected].