> ## 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 OIDC provider

> Connect OpenCX to any OpenID Connect provider using the authorization-code flow. Covers the redirect URI, client credentials, required scopes and claims, and group-to-role mapping.

Prefer OAuth 2.0 tooling, or run an OIDC-first IdP like **Keycloak**, **Auth0**, **Ping**, or the OIDC side of **Entra ID** / **Okta**? OpenCX supports OpenID Connect via the **authorization-code flow**. It delivers the same result as SAML; pick whichever your IdP handles best.

<Tip>
  Most enterprise IdPs default to SAML for third-party apps. If you don't have a specific reason to use OIDC, the [SAML guides](/security/sso/generic-saml) are the smoother path on Entra ID, Okta, and Google Workspace.
</Tip>

## The values you exchange

**Your IdP → OpenCX:**

| Value             | Notes                                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Issuer URL**    | Your IdP's OIDC issuer (e.g. `https://login.microsoftonline.com/{tenant-id}/v2.0`). OpenCX reads the discovery document at `/.well-known/openid-configuration`. |
| **Client ID**     | From the app/client you register.                                                                                                                               |
| **Client secret** | Generated when you create the client. Store it securely and share via your OpenCX contact's secure channel.                                                     |

**OpenCX → your IdP:**

| Value                                                                      | Where it goes                                                     |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Redirect URI**: `https://auth.open.cx/sso/oidc/{connection-id}/callback` | The client's allowed redirect / callback URI. Must match exactly. |

## Required scopes and claims

Request these scopes so OpenCX receives the claims it needs:

| Scope                                 | Provides                                                                                                                                 |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `openid`                              | The ID token (required).                                                                                                                 |
| `email`                               | `email` (and `email_verified`). OpenCX keys the member on this.                                                                          |
| `profile`                             | `given_name`, `family_name`, `name`.                                                                                                     |
| `groups` *(or your IdP's equivalent)* | Group membership for [role mapping](/security/sso/scim#role-mapping). Some IdPs expose this as a configurable claim rather than a scope. |

<Note>
  If your IdP doesn't emit `groups` in the ID token by default (Entra ID, for example, needs a **groups claim** configured on the app registration, and may emit object IDs), set it up explicitly; otherwise every member lands as the default role.
</Note>

## Setup

<Steps>
  <Step title="Register an OIDC client / app">
    In your IdP, create a **Web application** (confidential client) using the **authorization-code** grant.
  </Step>

  <Step title="Add the redirect URI">
    Set the allowed redirect URI to your OpenCX **Redirect URI** exactly, including scheme and path.
  </Step>

  <Step title="Configure scopes and the groups claim">
    Grant `openid`, `email`, `profile`, and your groups claim. Confirm `email` is included in the ID token.
  </Step>

  <Step title="Generate a client secret">
    Create a client secret and note its expiry. Set a calendar reminder to rotate it before it lapses, or logins will fail on expiry day.
  </Step>

  <Step title="Send credentials to OpenCX">
    Provide the **issuer URL**, **client ID**, and **client secret** to your OpenCX contact. We register them on your connection.
  </Step>
</Steps>

## 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 redirect to your IdP's consent/login 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

| Symptom                      | Likely cause                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `redirect_uri_mismatch`      | The registered redirect URI doesn't exactly match the OpenCX **Redirect URI**. |
| `invalid_client`             | Wrong client ID/secret, or the secret expired. Rotate and re-share.            |
| Everyone is the default role | Groups claim not configured or not present in the ID token.                    |
| Names blank                  | `profile` scope not granted, or `given_name` / `family_name` not emitted.      |

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