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

# Okta

> Connect OpenCX to Okta with a SAML 2.0 app integration. Covers the app wizard, attribute statements, group attribute statements, assignment, and SCIM provisioning.

Connect OpenCX to **Okta** with a SAML 2.0 app integration. You'll build the app with Okta's App Integration Wizard, exchange metadata, and (optionally) push groups and provision with SCIM.

## Before you start

<Steps>
  <Step title="Confirm your Okta role">
    You need **Super Administrator** or a custom admin role with rights to create app integrations.
  </Step>

  <Step title="Have your OpenCX SP details ready">
    | OpenCX value                                                      | Okta field                  |
    | ----------------------------------------------------------------- | --------------------------- |
    | **ACS URL**: `https://auth.open.cx/sso/saml/{connection-id}/acs`  | Single sign-on URL          |
    | **SP Entity ID**: `https://auth.open.cx/sso/saml/{connection-id}` | Audience URI (SP Entity ID) |
  </Step>
</Steps>

## 1. Create the SAML app

<Steps>
  <Step title="Start the App Integration Wizard">
    In the Okta Admin Console go to **Applications → Applications → Create App Integration**, choose **SAML 2.0**, and click **Next**.
  </Step>

  <Step title="Name the app">
    Set the app name to `OpenCX`, optionally upload the OpenCX logo, and click **Next**.
  </Step>

  <Step title="Enter the SAML settings">
    * **Single sign-on URL** → your OpenCX **ACS URL**
    * Leave **Use this for Recipient URL and Destination URL** checked.
    * **Audience URI (SP Entity ID)** → your OpenCX **SP Entity ID**
    * **Name ID format** → **EmailAddress**
    * **Application username** → **Email**
  </Step>
</Steps>

## 2. Add attribute statements

Okta doesn't send name attributes by default. Add these under **Attribute Statements**:

| Name        | Name format | Value            |
| ----------- | ----------- | ---------------- |
| `email`     | Basic       | `user.email`     |
| `firstName` | Basic       | `user.firstName` |
| `lastName`  | Basic       | `user.lastName`  |

For role mapping, add a **Group Attribute Statement**:

| Name     | Name format | Filter                                                              |
| -------- | ----------- | ------------------------------------------------------------------- |
| `groups` | Basic       | **Matches regex** `.*` (or **Starts with** a prefix like `opencx-`) |

<Tip>
  Use a filter that only emits the groups OpenCX cares about (e.g. **Starts with** `opencx-`) rather than every group a user belongs to. It keeps assertions small and your role mapping readable.
</Tip>

Click **Next**, choose **I'm an Okta customer adding an internal app**, and **Finish**.

## 3. Hand your metadata to OpenCX

<Steps>
  <Step title="Open the Sign On tab">
    In the app, go to **Sign On** → **SAML Signing Certificates** → **Actions → View IdP metadata** (or **Identity Provider metadata** link).
  </Step>

  <Step title="Send the metadata to OpenCX">
    Copy the metadata URL (preferred) or download the XML and give it to your OpenCX contact. We register your Okta issuer, SSO endpoint, and signing certificate on your connection.
  </Step>
</Steps>

## 4. Assign users and groups

<Steps>
  <Step title="Assign a pilot">
    Go to the app's **Assignments** tab → **Assign → Assign to People** and add a couple of pilot users.
  </Step>

  <Step title="Assign production groups">
    Once the pilot passes, **Assign to Groups** for the groups that should have OpenCX access. These are the same groups you filter into the `groups` attribute.
  </Step>
</Steps>

## 5. Test the login

<Steps>
  <Step title="IdP-initiated">
    Have a pilot user open their **Okta End-User Dashboard** and click the **OpenCX** tile. They should land in the OpenCX Inbox.
  </Step>

  <Step title="SP-initiated">
    In a private window, go to [platform.open.cx](https://platform.open.cx), enter the pilot's work email, and confirm the redirect to Okta and back.
  </Step>

  <Step title="Confirm the role">
    Verify the pilot received the expected OpenCX role. If not, check the group attribute statement filter and your [role mapping](/security/sso/scim#role-mapping).
  </Step>
</Steps>

## 6. (Optional) SCIM provisioning & group push

For automatic provisioning, deprovisioning, and group-driven roles, enable SCIM.

<Steps>
  <Step title="Request SCIM details from OpenCX">
    Ask for your **SCIM base URL** (`https://auth.open.cx/scim/v2/{connection-id}`) and a **bearer token**.
  </Step>

  <Step title="Enable provisioning in Okta">
    On the app, open the **Provisioning** tab → **Configure API Integration** → check **Enable API integration**, paste the base URL and token, then **Test API Credentials** and **Save**.
  </Step>

  <Step title="Turn on provisioning actions">
    Under **To App**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. Optionally use **Push Groups** to keep OpenCX group membership in sync for role mapping.
  </Step>
</Steps>

See [Provisioning & role mapping](/security/sso/scim) for the attribute reference.

## 7. Enforce

When the pilot is clean, ask OpenCX to enforce SSO for your domain. Read the [pre-cutover checklist](/security/sso/troubleshooting#before-you-enforce) first and secure your [break-glass account](/security/sso/overview#enforcement-break-glass).

## Troubleshooting

| Symptom               | Likely cause                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| User denied at Okta   | User isn't assigned to the app. Add them under **Assignments**.                                     |
| Lands as default role | `groups` attribute statement missing or filtered out; or group names aren't in your OpenCX mapping. |
| Names show as blank   | `firstName` / `lastName` attribute statements not added.                                            |

More in [Troubleshooting SSO](/security/sso/troubleshooting).