# System for Cross-Domain Identity Management (SCIM)

SCIM lets your Identity Provider (IdP) manage StackAI access automatically. You can use it to automate onboarding and offboarding of users without manual intervention.

Use SCIM when users are managed centrally in Okta or Entra ID. Changes apply when people join, move teams, or leave.

### Why SCIM helps

SCIM keeps your StackAI user access in sync with your IdP.

* Provision users when they’re added in your IdP.
* Deprovision users when they leave your organization.
* Assign roles based on IdP role or group attributes.
* Sync groups from your IdP into StackAI.

### Key concepts

* **SCIM token**: Bearer token used by your IdP to authenticate provisioning calls.
* **Role mapping**: Rule that maps an IdP role value to a StackAI role.
* **Disable mode**: Behavior for SCIM-managed users when SCIM is turned off.

### Before you begin

You need two things before you can enable SCIM:

1. **SSO configured** in **Settings** → **SSO Settings**.
2. Once SSO is configured, head to **Settings → Provisioning** to configure SCIM provisioning. Note that **a default role must be selected**. All provisioned users receive this role unless a role mapping applies.

{% hint style="info" %}
You cannot enable SCIM until SSO is active for your organization.
{% endhint %}

### Supported identity providers

StackAI supports any SCIM 2.0-compliant IdP, including:

* Microsoft Entra ID (Azure AD)
* Okta
* Google Workspace
* Ping Identity
* JumpCloud
* OneLogin
* Auth0
* Others (SCIM 2.0-compliant)

### Set up SCIM

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2F6IkgVdf1ZeyIKlTS1hqA%2Fscim.mp4?alt=media&token=88625c5e-f5ee-440a-a107-156a6c37082c>" %}

{% stepper %}
{% step %}

#### Open SCIM provisioning in StackAI

Go to **Settings** → **Security** → **SCIM Provisioning**.

Select your Identity Provider, set a **Default role**, and copy the SCIM Base URL: `https://api.stack-ai.com/scim/v2`
{% endstep %}

{% step %}

#### Generate a SCIM token

Under **SCIM Tokens**, select **Create token**.

Set a name, like `Okta Production` and optionally set an expiration date.

Copy the token immediately — it is only shown once.
{% endstep %}

{% step %}

#### Configure your IdP

In your IdP’s SCIM settings, enter:

* **SCIM Base URL:** `https://api.stack-ai.com/scim/v2`
* **Authentication method:** Bearer token
* **Bearer token:** the token you generated
  {% endstep %}

{% step %}

#### Enable SCIM

Toggle on **Enable SCIM** in the overview section. If it’s disabled, check SSO, default role, and IdP selection.
{% endstep %}
{% endstepper %}

### Role mappings

All SCIM-provisioned users get the **Default role** by default. Role mappings let you assign specific StackAI roles based on roles sent by the IdP.

When your IdP sends a role attribute (like `Admin`), StackAI checks the role mapping table and assigns the matching role. If no mapping matches, the **Default Role** applies.

#### Create a role mapping

1. Go to Settings → Provisioning → Role Mappings.
2. Click **Add Mapping**.
3. Enter the **IdP Role Value** — the exact role name as sent by your IdP.
4. Select the target **StackAI Role** (refresher on StackAI Roles can be found [here](https://docs.stackai.com/governance-and-security/role-based-access-controls-rbac-and-groups))
5. Save.

{% hint style="info" %}
Role values are case-insensitive. Admin and admin resolve to the same mapping.
{% endhint %}

### What gets synced

#### Users

StackAI supports the full user lifecycle.

* **Provision**: Create new users.
* **Update**: Sync attributes like name and email.
* **Deactivate**: Setting `active: false` deactivates the user in StackAI.
* **Reactivate**: Setting `active: true` restores access.

#### Groups

When **Sync groups** is enabled, IdP groups are mirrored in StackAI. Membership changes in the IdP sync automatically.

### Disable SCIM

When you disable SCIM, choose a disable mode:

* **Soft (default)**: SCIM-managed users remain active. They keep their access but are no longer externally managed.
* **Lock**: SCIM-managed users are deactivated. They lose access until manually reactivated by an Admin.

In both modes, StackAI revokes all SCIM tokens.

{% hint style="warning" %}
Lock mode immediately removes access for all SCIM-provisioned users. Use Soft mode if you want to preserve existing access during a transition.
{% endhint %}

### Token management

* Create multiple tokens — useful for rotating credentials with zero downtime.
* Revoke a token — takes effect immediately. The IdP will receive 401 errors until a new token is configured.
* Set an expiration — optional. Tokens without an expiration remain valid until revoked.

{% hint style="info" %}
Token values are stored as secure hashes and are only shown once at creation time. If you lose a token, revoke it and create a new one.
{% endhint %}

### Configuration options

* **Default role** (required): Role applied when no role mapping matches.
* **Auto-activate users** (default on): Activates new users when provisioned.
* **Sync groups** (default on): Mirrors IdP groups into StackAI.

### Troubleshooting

* **"The Enable SCIM toggle is grayed out"**: SSO must be configured, a default role must be set, and an IdP must be selected before you can enable SCIM.
* **"A provisioned user has the wrong role"**: Check your role mappings. If the IdP role value doesn't exactly match a mapping, the user falls back to the Default Role.
* **"The IdP is returning 401 errors"**: Your SCIM token may have been revoked or expired. Generate a new token and update your IdP configuration.
* **"A user was provisioned but can't log in"**: Confirm SSO is active and that the user's email in the IdP matches their StackAI profile. Email matching is case-insensitive.