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

# Provisioning & role mapping

> How OpenCX provisions SSO members, just-in-time and SCIM 2.0, and how to map identity-provider groups to OpenCX roles (admin, agent, viewer).

OpenCX creates and updates member accounts from your identity provider so you don't manage a second user list. This page covers the two provisioning modes and how directory groups become OpenCX roles.

## Provisioning modes

### Just-in-time (JIT)

This is the default and works with every provider. The first time someone authenticates through your IdP, OpenCX reads the assertion/ID token and:

1. Creates a member record from `email`, `firstName`, and `lastName`.
2. Assigns a role from your [group mapping](#role-mapping) (or the default role if no group matches).
3. Issues a session.

On later logins, OpenCX refreshes the member's name and re-evaluates their role from the current group claim, so a promotion in your directory takes effect on next login.

<Warning>
  **JIT does not deprovision.** Disabling a user in your IdP blocks their *next* login, but an already-issued OpenCX session stays valid until it expires. For immediate offboarding, use **SCIM**: or shorten session lifetime with your OpenCX contact.
</Warning>

### SCIM 2.0

Available on request. Your IdP pushes lifecycle events to OpenCX in real time, create, update, **deactivate**: so members are provisioned and deprovisioned without waiting for a login. Recommended for larger teams and strict offboarding SLAs.

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

  <Step title="Configure your IdP's provisioning">
    Point your IdP's SCIM/provisioning integration at the base URL with the bearer token. Provider-specific steps: [Entra ID](/security/sso/microsoft-entra#7-optional-scim-provisioning), [Okta](/security/sso/okta#6-optional-scim-provisioning-group-push).
  </Step>

  <Step title="Scope to assigned users">
    Set provisioning scope to *assigned users and groups only* so you don't sync your entire directory.
  </Step>
</Steps>

**Supported SCIM resources & operations:**

| Resource | Operations                                                      |
| -------- | --------------------------------------------------------------- |
| Users    | Create, read, update (name/email/active), deactivate            |
| Groups   | Create, read, update membership (for group push → role mapping) |

<Note>
  Google Workspace does not offer SCIM to third parties, Google-backed connections use JIT only.
</Note>

## Attribute reference

OpenCX consumes these attributes from SAML assertions, OIDC ID tokens, or SCIM payloads:

| OpenCX field         | SAML / OIDC claim          | SCIM attribute                 | Required            |
| -------------------- | -------------------------- | ------------------------------ | ------------------- |
| Email (identity key) | Name ID / `email`          | `userName` / `emails[primary]` | Yes                 |
| First name           | `firstName` / `given_name` | `name.givenName`               | Recommended         |
| Last name            | `lastName` / `family_name` | `name.familyName`              | Recommended         |
| Groups               | `groups`                   | group membership               | For role mapping    |
| Active               | ,                          | `active`                       | SCIM deprovisioning |

## Role mapping

OpenCX has three roles. Map your IdP groups to them so directory changes drive access.

| OpenCX role | Can do                                                                |
| ----------- | --------------------------------------------------------------------- |
| **Admin**   | Full access, settings, integrations, billing, members, and the Inbox. |
| **Agent**   | Work the Inbox, reply, hand off, resolve. No org settings.            |
| **Viewer**  | Read-only access to conversations and reports.                        |

<Steps>
  <Step title="Decide your group → role rules">
    Draw up which IdP groups map to which roles, for example:

    | IdP group         | OpenCX role |
    | ----------------- | ----------- |
    | `opencx-admins`   | Admin       |
    | `support-agents`  | Agent       |
    | `support-viewers` | Viewer      |
  </Step>

  <Step title="Give OpenCX the group identifiers">
    Send the group names, or **object IDs** if your IdP emits IDs rather than names (Entra ID does), to your OpenCX contact along with the target role for each.
  </Step>

  <Step title="Set the default role">
    Choose the role for members whose groups match nothing. **Viewer** is the safe default; escalate deliberately.
  </Step>
</Steps>

<Warning>
  **Precedence:** if a user is in multiple mapped groups, OpenCX grants the **highest** role among the matches. Keep an eye on broad groups: a user in both `support-viewers` and `opencx-admins` becomes an Admin.
</Warning>

<Tip>
  Emit only the groups OpenCX needs (filter in Okta, use *Groups assigned to the application* in Entra) rather than every group a user belongs to. Smaller assertions, clearer mappings, fewer surprises.
</Tip>

## Related

* [SSO overview](/security/sso/overview)
* [Troubleshooting SSO](/security/sso/troubleshooting)