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

# Any SAML 2.0 IdP

> Connect OpenCX to any SAML 2.0 identity provider, OneLogin, JumpCloud, Ping Identity, Duo, Auth0, or on-prem AD FS. The SP values, required assertion shape, and signing rules.

Any standards-compliant SAML 2.0 identity provider works with OpenCX. Use this guide for **OneLogin**, **JumpCloud**, **Ping Identity / PingFederate**, **Duo SSO**, **Auth0**, on-prem **Microsoft AD FS**, or anything else that speaks SAML 2.0. The mechanics are identical, only the admin console differs.

<Info>
  If you're on **Microsoft Entra ID**, **Okta**, or **Google Workspace**, use the dedicated guide instead; it names the exact screens: [Entra ID](/security/sso/microsoft-entra), [Okta](/security/sso/okta), [Google Workspace](/security/sso/google-workspace).
</Info>

## The values you exchange

You give OpenCX your IdP metadata; OpenCX gives you the service-provider (SP) values below. Every SAML IdP has a field for each.

**OpenCX → your IdP (SP values):**

| OpenCX value                                                      | Common IdP field names                                                    |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **SP Entity ID**: `https://auth.open.cx/sso/saml/{connection-id}` | Audience, Audience URI, Entity ID, SP Entity ID, Relying Party Identifier |
| **ACS URL**: `https://auth.open.cx/sso/saml/{connection-id}/acs`  | ACS URL, Reply URL, Consumer URL, Recipient, Destination                  |
| **Sign-on URL**: `https://platform.open.cx/login`                 | Sign-on / login URL (optional)                                            |

**Your IdP → OpenCX (metadata):** your IdP **metadata URL** (preferred) or **metadata XML**, which contains your issuer/entity ID, SSO endpoint, and signing certificate. Hand this to your OpenCX contact.

## Required assertion shape

For OpenCX to accept a login, the signed SAML response must satisfy all of the following:

<AccordionGroup>
  <Accordion title="Name ID is the user's email" icon="at">
    Set **Name ID format** to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` and the value to the user's primary email. OpenCX keys the member identity on this, a non-email Name ID (e.g. a directory GUID) causes duplicate accounts on re-login.
  </Accordion>

  <Accordion title="Email, first name, last name attributes" icon="user">
    Send these attributes so OpenCX can create and display members:

    | Attribute  | Accepted names                                                                   |
    | ---------- | -------------------------------------------------------------------------------- |
    | Email      | `email`, or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
    | First name | `firstName`, `givenName`, or `.../claims/givenname`                              |
    | Last name  | `lastName`, `surname`, or `.../claims/surname`                                   |
  </Accordion>

  <Accordion title="Group attribute (for role mapping)" icon="users">
    To drive OpenCX roles from your directory, send a multi-valued `groups` attribute containing the user's group names or IDs. Map these to OpenCX roles in [role mapping](/security/sso/scim#role-mapping). Without it, everyone lands as the default role.
  </Accordion>

  <Accordion title="Signature" icon="signature">
    The SAML **response and/or assertion must be signed** with your IdP's certificate (the one in your metadata). OpenCX rejects unsigned assertions. Signed **and** encrypted assertions are supported on request.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Create a SAML app in your IdP">
    Create a new SAML 2.0 application (sometimes called "relying party trust" in AD FS, "connector" in Auth0, or "custom SAML app" elsewhere).
  </Step>

  <Step title="Enter the OpenCX SP values">
    Paste the **SP Entity ID** and **ACS URL** from the table above into your IdP's audience/entity and ACS/reply fields.
  </Step>

  <Step title="Set Name ID and attributes">
    Configure Name ID as **email**, and add the **email / first name / last name** attributes (and `groups` if you're mapping roles).
  </Step>

  <Step title="Sign the assertion">
    Ensure response/assertion signing is enabled with your IdP certificate.
  </Step>

  <Step title="Send your metadata to OpenCX">
    Give us your metadata URL (preferred) or XML. We register your issuer, SSO endpoint, and certificate on your connection.
  </Step>

  <Step title="Assign users">
    Grant a pilot group access in your IdP, then expand once it passes.
  </Step>
</Steps>

## AD FS specifics

<AccordionGroup>
  <Accordion title="Relying party trust" icon="microsoft">
    Add a **Relying Party Trust** → **Enter data manually** (or import the OpenCX SP metadata if you're given a URL). Use the **ACS URL** as the SAML 2.0 SSO service endpoint and the **SP Entity ID** as the relying party identifier.
  </Accordion>

  <Accordion title="Claim rules" icon="list-check">
    Add a **Send LDAP Attributes as Claims** rule mapping **E-Mail-Addresses → E-Mail Address**, **Given-Name → Given Name**, **Surname → Surname**, and **Token-Groups → a `groups` claim**. Then a **Transform** rule mapping the **E-Mail Address** claim to **Name ID** with format **Email**.
  </Accordion>

  <Accordion title="Metadata URL" icon="link">
    AD FS publishes federation metadata at `https://<your-adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml`. Give that URL to OpenCX so certificate rollovers are picked up automatically.
  </Accordion>
</AccordionGroup>

## Test and enforce

<Steps>
  <Step title="Test SP-initiated login">
    In a private window, go to [platform.open.cx](https://platform.open.cx), enter a pilot's work email, and confirm the round trip to your IdP and back into the Inbox.
  </Step>

  <Step title="Confirm the role">
    Verify the pilot's OpenCX role matches your group mapping.
  </Step>

  <Step title="Enforce">
    When clean, ask OpenCX to enforce SSO. Read the [pre-cutover checklist](/security/sso/troubleshooting#before-you-enforce) and secure your [break-glass account](/security/sso/overview#enforcement-break-glass).
  </Step>
</Steps>

## Troubleshooting

See [Troubleshooting SSO](/security/sso/troubleshooting) for assertion, attribute, clock-skew, and certificate errors that apply to every SAML IdP.