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

# Organization roles and inherited access

> Create local permission sets and distinguish inherited roles from editable roles. Use this guide when managing access across connected organizations.

Open **Settings → Roles** to see the permission sets available in your organization. Editing local roles requires **Roles: Write**. Members with **Directory role mappings: Write** also have role-editing access; role-editing access alone does not grant mapping access.

## Local roles

Use **Create Role** to define a name, description, default workspace, and permissions. Local role names must be unique among local roles in the organization.

Local roles remain editable when the organization also has inherited roles. Their existing assignments remain separate from inherited copies.

## Inherited roles

Inherited roles appear in a separate **Inherited roles** section below local roles. They show their permissions and members, but have no edit or delete action. Changes to their definitions must be made through the source role in the main billing organization. Direct API attempts to edit or delete an inherited copy are rejected.

For a child configured to inherit directory mappings, only the main organization's mapped roles are copied. Mapping a role creates its inherited copy; changes to that source role update the copy. Unmapped main-organization roles are not copied.

An inherited role remains while at least one main-organization mapping grants it. Removing its last mapping removes the inherited copy and its assignments when the mapping change is applied. Review the affected child organizations and members in the preview before confirming. Local child roles and children with independent mappings are unaffected.

A local role and an inherited role can share a name, such as **Support**. They are separate roles with separate IDs and may grant different permissions. Member role selectors label inherited roles with **(Inherited)** to distinguish them.

When inherited copies become independent local roles, conflicting names receive an **(Inherited)** suffix. If that name is already taken, a number is added. The role IDs, permissions, assignments, and mappings are retained. The names must match the confirmed preview; if they change before applying, review the change again.

## Role permissions

A member's permissions combine the permissions of their assigned roles. A member with no assigned roles has no role permissions. Full administrator access requires an explicitly assigned role with the full-access permission.

When directory role management is active, directory-linked members receive their complete role set from the mappings. Manual assignment changes are rejected for those members. Unrelated manually managed members retain their local assignments, and the organization owner remains exempt from automatic role synchronization.

Deleting a local role removes its assignments. A role referenced by directory mappings cannot be deleted until those references are removed through a confirmed mapping change.

## Directory mappings

In the main billing organization, open **Settings → Security → Directory role sync** and turn on **Import groups and memberships**. Configure your identity provider to provision groups and their direct memberships to the displayed SCIM Tenant URL. This starts an import; it does not activate automatic role changes.

Open **Settings → Roles → Directory mappings**. This tab requires **Directory role mappings: Read**; editing and applying mappings requires **Directory role mappings: Write**. Enabling the import in Security also requires settings-write access.

All directory mappings are configured from the main billing organization. Use the organization selector to manage a selected child's independent mappings. In a child organization, the tab shows its own mappings read-only and links to the main organization. Local role definitions remain editable under the existing role permissions; inherited roles remain read-only.

Under **Managed organizations**, set each non-partner suborganization to **Inherit from main organization**, **Own mappings**, or **Not included**, or turn on **Include all suborganizations** to include every current and future one. The main billing organization is always included. Changing scope requires both settings-write and directory-mapping-write permission in the main organization, including at confirmation.

Choose whether included children inherit the main organization's mapped roles and mappings or use their own mappings. **Default role setup** applies a choice to all included children; you can then customize individual children. Future included children use the default choice. Inheritance preserves existing local role definitions and manually managed members; inherited definitions remain read-only.

Use **Preview changes** before applying scope or inheritance changes. The preview lists new memberships, role changes, inherited roles becoming local, and deactivations for users already offboarded in the directory. Active SCIM users are provisioned into newly included organizations. With role sync active, linked members without a matching grant receive no role permissions. Owners are exempt from role synchronization and are never deactivated.

Removing a child from scope **preserves its current access**. Members, roles, and mappings remain; inherited copies become editable local roles, with collision renames shown in the preview. Future provisioning, role synchronization, and offboarding exclude that child. Its saved mappings remain visible from the main organization. Including it again requires another preview and applies the directory's current state, including any offboarding that occurred while it was excluded.

Each external source has one row. Select one or more OpenCX roles, or explicitly select **No roles** for a group used only to assign the application. Unreviewed sources are marked in the table and listed by name below it. Clearing the role selection leaves a source unreviewed until you deliberately select **No roles**.

Use **Preview mapping changes** to review and save the mappings. During import, saving mappings leaves existing assignments unchanged. Once the mappings are ready, use **Preview activation**. The preview identifies the memberships that will become directory-managed and lists the role additions and removals. Confirm with **Activate role sync**.

Existing accounts linked to the selected directory are included, even if they belong to no group. Matching an email address alone does not establish a directory link. Unrelated manual members remain manually managed, and owners retain their existing roles.

After activation, mapping changes still require a preview and confirmation. They recalculate current members' roles without waiting for another directory update. A preview belongs to the administrator who created it; changes to directory access before confirmation require a new preview. Previews expire after 15 minutes.

For a directory paired with an SSO connection, validated login claims can also update group and application-role assignments. Groups and application-role values are separate mapping sources, even when their identifiers contain the same text. Their grants combine: a role remains assigned while any verified source grants it. Other SSO connections do not change directory-managed roles.

Configure **Sign-in role updates** under **Settings → Security** in the main billing organization. This requires both SSO write permission and `settings-scim-role-mappings:write`. Select one SSO connection and enter the exact field names containing groups and application roles. Each field accepts a single string or a list of strings; values are matched exactly, without splitting commas or changing case. Group identifiers must match the identifiers imported through SCIM. Leave a field blank if that claim should not contribute roles.

The optional **Directory user ID claim field** binds a validated SSO login to its stable directory object ID for provider verification. Use the field containing the directory's object ID, never an email address or an identifier from an unrelated SSO connection. A missing value preserves the previous verified binding. A conflicting value is logged and prevents provider-based reconciliation for that member until the login configuration is reviewed; it does not silently move the member to another identity. Changing login configuration clears its previous identity bindings as well as its role observations. SCIM account identifiers remain independently available.

Turn on directory import and sign in through the selected connection to verify complete claims before previewing activation. Configure your provider to send direct, application-assigned groups consistently across provisioning and login. Missing claims and group-overage indicators cannot verify the configuration.

To change the selected SSO connection or either claim field after activation, first disable **Directory role sync** through its preview. Current assignments become manually managed. Save the new login settings, turn import back on, verify fresh complete claims, and preview activation again. Old login observations are discarded; SCIM evidence and saved mappings remain. A login begun under the old claim configuration cannot verify the new one.

A confirmed empty claim removes the grants supplied by that claim. Missing, malformed, or incomplete claims preserve the last verified grants and record a sync error. A new managed member with no verified grants receives no role permissions. Conflicting SCIM and login observations preserve the last verified membership while reconciliation is needed; whichever request arrives last does not automatically win.

Members who retain organization access stay signed in when a directory update changes their roles. Their dashboard refreshes permission state. Feature-specific filtering of shared live updates is not included in this release; retaining membership can still allow shared events to arrive after a role reduction. SCIM offboarding removes the managed organization membership and disconnects its live access; a subsequent SSO login cannot restore that membership while the directory still marks the user inactive.

To stop automatic role changes, turn off **Import groups and memberships** under **Settings → Security → Directory role sync** and confirm the preview. Current role assignments are preserved and can be managed manually. Groups and memberships continue importing while role sync is off, and SCIM user provisioning remains enabled. Re-enabling role sync returns to setup; it does not reactivate role enforcement until a new activation preview is confirmed.

### Disconnecting SCIM

In the main billing organization's SCIM settings, select **Remove SCIM connection** and review the disconnect preview. Confirm with **Disconnect and preserve access**. This requires settings-write and directory-mapping-write permission. Existing memberships and role assignments remain. Inherited roles become editable local copies; name collisions receive an **(Inherited)** suffix, shown in the preview. Automatic provisioning, role updates, and the optional connector stop, and the token, saved mappings, connector credentials, and old sync records are removed. SSO login settings remain configured.

Deactivated memberships stay deactivated after disconnecting, and an SSO sign-in doesn't reactivate them: reactivate them in **Settings → Members**, or through a new provisioning connection. Historical account bans remain unchanged. Reconnecting requires fresh import, mapping review, and activation. Remove any optional event relay deployed in your provider separately if it is no longer needed.

An SSO connection paired with directory role sync cannot be deleted directly. Disable role sync and clear its selected login connection first, or complete the SCIM disconnect preview before deleting that SSO connection.

## Reading roles through the API

[Role list](https://docs.open.cx/api-reference/roles/list.md) and [role detail](https://docs.open.cx/api-reference/roles/get.md) responses include `is_inherited`. [User responses](https://docs.open.cx/api-reference/users/list.md) include the same flag on their role summaries. Use role IDs for matching and assignment, because local and inherited names can be equal.

## Optional Microsoft Entra connector

The optional connector verifies current directory data when changes arrive. It complements SCIM and login claims; it does not provide a guaranteed delivery time. Configure it from the main billing organization under **Settings → Security → Microsoft Entra connector**. You need both settings write permission and `settings-scim-role-mappings:write`.

1. In your Entra tenant, register an application that OpenCX can use to read directory data. Grant the Microsoft Graph **application permissions** `Application.Read.All`, `Group.Read.All`, and `User.Read.All`, and have a tenant administrator grant consent. Delegated permissions do not authorize background reads.
2. Create a client secret for that application. Copy its **value**, not its secret ID. Record its expiration date and arrange to rotate it before expiry.
3. Find the **object ID of the enterprise application used for OpenCX sign-in and assignments**. This is distinct from the client ID of the application you registered for directory reads.
4. Enter the tenant ID, enterprise application object ID, client ID, and client secret value in OpenCX. Optionally record the secret expiration date. Select **Verify and connect**.
5. Review imported groups and application-role values in **Settings → Roles → Directory mappings**. Configure the mappings, then preview and activate role enforcement. Only direct group membership contributes access.

OpenCX encrypts the client secret and does not return it in settings responses. It obtains access tokens using the application credentials; you do not supply refresh tokens or replace short-lived access tokens yourself. To rotate credentials, supply a valid client ID and new secret value, then select **Verify and update credentials**. Failed verification leaves the previous credentials intact. The tenant and enterprise application remain fixed for that directory connection. Moving to another directory requires disconnecting the old directory and repeating import, mapping review, and activation.

Group and user notifications trigger verification of current directory data. An incomplete read, permission failure, or provider outage preserves the last verified role grants and records an error for retry. Unknown user identities are not matched by email. The connector does not schedule periodic reads of membership or application-role assignments.

When the connector confirms an account is disabled or deleted, OpenCX deactivates that person's memberships in the directory's managed organizations. Access to unrelated organizations remains. A delayed SCIM activation cannot undo that deactivation: OpenCX must first verify that the same directory account is enabled and eligible for the configured application. If verification fails, the memberships stay deactivated and SCIM receives a retryable error. Successful reactivation uses current verified group and application-role assignments. Existing historical global bans are preserved for explicit migration.

### Application-role audit relay

Microsoft Graph notifications do not cover every application-role assignment change. To detect direct user or group app-role assignment changes between logins, deploy the optional audit relay in your Azure subscription. Without the relay, those changes can remain undetected until another relevant event or login triggers a refresh.

Select **Create relay token**, copy the token once, and save its endpoint. The relay token is separate from the client secret. [Download the relay deployment package](https://docs.open.cx/downloads/entra-audit-relay.zip), extract it, and open `setup.html` for the deployment and verification steps. The package includes the resource templates, forwarding function, and commands for exporting Entra audit events. Your Azure administrator must review the resources, permissions, retention, and running costs before deployment.

The relay forwards successful application-management event identifiers to OpenCX. OpenCX reads current assignments before applying changes; the event payload itself does not grant permissions. Failed delivery retries and duplicate events are handled without granting duplicate roles. Provider replication, event delivery, throttling, and failures can delay updates. Retention limits can also leave gaps after a prolonged outage; validate delivery and monitor failures before relying on the faster path.

Use **Replace relay token** only when ready to update the relay configuration. The previous token stops working immediately, so delivery resumes after the replacement is installed. This does not change SCIM provisioning or current OpenCX roles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.