# SCIM provisioning

SCIM (System for Cross-domain Identity Management) lets your IdP automatically create, update, and deactivate Agility Credit users based on assignments and group memberships in your IdP. When SCIM is enabled, your IdP becomes the source of truth for user lifecycle and role assignment.

SCIM is configured under **Settings → Account → Identity → SCIM**.

*(Screenshot: SCIM 1)*

## When to use SCIM

Use SCIM if you want:

- **Automatic provisioning** — Users get an Agility account the moment they're assigned to the Agility app in your IdP.
- **Automatic deprovisioning** — Removing a user from the app or disabling them in your IdP locks them out of Agility.
- **Group-driven roles** — Role changes in your IdP flow through to Agility on the next sync, not on the next sign-in.

If you only need authentication, **don't enable SCIM** — just use SSO with role mapping. SCIM adds operational overhead and requires the user to exist in Agility _before_ their first sign-in.

## SCIM × SSO behavior

| Scenario                       | Without SCIM                                      | With SCIM                                                    |
| ------------------------------ | ------------------------------------------------- | ------------------------------------------------------------ |
| New user signs in via SSO      | Auto-created (JIT); roles from your role mapping  | Sign-in rejected with `scim_required_user_not_provisioned`   |
| Existing user signs in via SSO | Roles re-synced from role mapping every sign-in   | Roles read from the SCIM-managed record; SSO mapping ignored |
| User removed in IdP            | Account remains in Agility until manually deleted | Deprovisioned automatically on the next SCIM sync            |

## Supported IdPs

Agility's SCIM endpoint is SCIM 2.0–compliant and is officially supported with:

- **Okta** — using Okta's SCIM 2.0 provisioning
- **Microsoft Entra ID** — using Entra's SCIM provisioning

Other SCIM 2.0 clients may work — if your IdP sends a valid SCIM 2.0 bearer-authenticated payload, our endpoint will respond — but they are not officially tested or supported.

## Enable SCIM

### Step 1: Create an API key

SCIM authenticates using an Agility API key as a bearer token.

1. In the portal, go to **Settings → Account → API Keys**.
2. Click **Create API key**, give it a descriptive name (e.g. `Okta SCIM`), and save.
3. **Copy the full key value** — Agility only displays it once.

*(Screenshot: SCIM 2)*

:::tip Use a dedicated key
Create a separate API key for SCIM rather than reusing one used by other integrations. That way you can rotate it independently if your IdP credentials are compromised.
:::

### Step 2: Enable SCIM in Agility

1. Go to **Settings → Account → Identity** and open the **SCIM** tab.
2. Toggle **Enable SCIM provisioning** on.
3. Note the **SCIM endpoint** URL displayed in the page — it's of the form:

   ```
   https://api.agilitycredit.net/scim/v2/<your-tenant-id>
   ```

   (UAT uses `https://api.agc-dev.com/scim/v2/<your-tenant-id>`. The exact value for your tenant is shown in the portal with a copy button.)

4. Click **Save**.

### Step 3: Configure your IdP

#### Okta

1. In your Okta app, go to **Provisioning → To App**.
2. Click **Configure API Integration**, check **Enable API integration**.
3. Enter:
   - **Base URL:** the SCIM endpoint from Agility
   - **Unique identifier field for users:** `userName`
   - **Authentication Mode:** **HTTP Header**
   - **Authorization:** paste the API key from Step 1 (Okta uses this verbatim as the `Authorization: Bearer <key>` header)
4. Click **Test API Credentials**, then **Save**.
5. Under **Provisioning → To App → Provisioning Settings**, enable the actions you need:
   - **Push New Users** — create users in Agility when assigned in Okta
   - **Push Profile Updates** — keep user attributes (name, email, phone) in sync
   - **Push Groups** — sync Okta groups to Agility (required if you use **From IdP groups** role mapping with SCIM)

:::caution Pick `userName` as the unique identifier
Agility's SCIM endpoint matches users by the SCIM 2.0 standard `userName`. If you pick anything else (e.g. `email` or `id`), Okta can't reliably correlate the Okta user to the Agility record across attribute changes — every update will create a new duplicate user in Agility.
:::

*(Screenshot: SCIM 3)*

#### Entra ID

1. In your Entra Enterprise Application, go to **Provisioning**.
2. Set **Provisioning Mode** to **Automatic**.
3. Under **Admin Credentials**, enter:
   - **Tenant URL:** the SCIM endpoint from Agility
   - **Secret Token:** the API key from Step 1
4. Click **Test Connection**, then **Save**.
5. Under **Mappings**, review and customize the attribute mappings if needed (the defaults work for most setups).
6. Set **Provisioning Status** to **On**.

*(Screenshot: SCIM 4)*

##### Recommended: provision roles via App Roles

If you're driving role assignment with **App Roles** (see [Set up Entra ID](https://apidocs.agilitycredit.com/sso/setup-entra)), add one extra attribute mapping so Entra pushes role assignments through SCIM:

1. In the Enterprise Application → **Provisioning → Mappings**, open **Provision Microsoft Entra ID Users**.
2. Scroll to **Attribute Mappings** and click **Add New Mapping**.
3. Configure:
   - **Mapping type:** Expression
   - **Expression:** `SingleAppRoleAssignment([appRoleAssignments])`
   - **Target attribute:** `roles[primary eq "true"].value`
   - **Match objects using this attribute:** No
   - **Apply this mapping:** Always
4. **Save**.

(If users in your tenant need multiple concurrent app roles, use the expression `AppRoleAssignmentsComplex([appRoleAssignments])` with the target attribute `roles`. `SingleAppRoleAssignment` is the common case.)

Without this mapping, app role assignments stay in Entra but aren't pushed to Agility — SCIM-provisioned users would arrive without roles. In Agility's role mapping, set **Source** to **From IdP attribute** and **Attribute name** to `roles`.

### Step 4: Assign users and run the initial sync

1. In your IdP, assign the users (and groups) you want provisioned.
2. Trigger an initial sync — both Okta and Entra do this automatically once provisioning is on.
3. In Agility, switch to the **Activity** tab and watch for `scim_provision` events. Successful provisioning events appear with the user's email and an HTTP 201 status.

## What gets synced

- **Users** — Email, given name, family name, active state
- **Groups** — Membership (used for role mapping if you've configured **From IdP groups**)
- **Roles** — Derived from SCIM data according to your role mapping configuration (see below)

## Role mapping with SCIM

The same role mapping configuration applies to SCIM-provisioned users — but it runs at **provisioning time**, not at sign-in time. Pick one of:

- **Portal-managed** — SCIM does not update roles. Administrators set them in the Agility portal.
- **From IdP groups** — Roles derived from SCIM group memberships. Updates to group membership in your IdP flow through on the next sync.
- **From IdP attribute** — Roles derived from a configurable SCIM user attribute.

See [Role mapping](https://apidocs.agilitycredit.com/sso/role-mapping) for full details.

## Monitoring SCIM activity

The **Activity** tab on the Identity page shows recent SCIM operations:

- `scim_provision` — User created or updated
- `scim_deprovision` — User deactivated
- `scim_error` — A SCIM request failed (with details)

Toggle **Log successful events (debug)** on to also record `scim_read` events, which include the full request and response payloads. Useful for diagnosing attribute mapping problems; disable it after go-live to keep the log readable.

## SCIM and SSO-exempt users

A user provisioned by SCIM can be [SSO-exempt](https://apidocs.agilitycredit.com/sso/sso-exempt-users), and creating or updating them over SCIM keeps the exemption. Deactivating or deleting them over SCIM removes it, and that's audited and emailed to your administrators. Because your IdP can still deactivate or demote such a user, keep emergency access accounts out of the users and groups assigned to the Agility app in your IdP.

## Disabling SCIM

If you turn SCIM off:

- Existing user records stay in Agility — they aren't deleted.
- New SSO users start being JIT-created again on first sign-in.
- Roles are managed by role mapping on every SSO sign-in (or stay manual if you chose **Portal-managed**).

## Troubleshooting

See the [Troubleshooting](https://apidocs.agilitycredit.com/sso/troubleshooting) page for common SCIM errors and how to read the activity log.

Source: https://apidocs.agilitycredit.com/sso/scim-provisioning