# SCIM Provisioning

SCIM (System for Cross-domain Identity Management) is an open standard ([RFC 7644](https://www.rfc-editor.org/rfc/rfc7644)) for automating user provisioning and deprovisioning between identity providers and service providers. Aritma IAM supports SCIM 2.0.

With SCIM, your identity provider (such as Microsoft Entra ID or Okta) automatically syncs users and groups to Aritma. When you add a user to a group in your IdP, they are provisioned in Aritma. When you remove them, they are deprovisioned.

## How it works

1. You create a SCIM token in Aritma IAM
2. You configure your identity provider with the Aritma SCIM endpoint and the token
3. Your identity provider pushes user and group changes to Aritma automatically
4. Aritma creates, updates, or deactivates user subjects based on the incoming SCIM events


## SCIM endpoint

Your Aritma SCIM endpoint is:


```
https://id.aritma.io/{tenantId}/api/scim/v2
```

This endpoint implements the SCIM 2.0 protocol. Identity providers use standard SCIM operations (`POST`, `GET`, `PUT`, `PATCH`, `DELETE`) on `/Users` and `/Groups` resources at this base URL.

## Step 1: Create a SCIM token

**Request body:**

| Field | Required | Description |
|  --- | --- | --- |
| `provider` | Yes | The scheme name of the SSO identity provider to associate with this token |
| `providerDisplayName` | Yes | The human-readable name of the identity provider |


The `provider` must match the `scheme` of an existing SSO provider on your tenant. This links the SCIM token to a specific identity provider configuration.

Save your token
The `token` value is only shown once. Copy it immediately and store it securely - you will need it when configuring your identity provider. It cannot be retrieved again.

## Step 2: Configure your identity provider

### Microsoft Entra ID (Azure AD)

1. In the [Azure portal](https://portal.azure.com), go to **Entra ID** > **Enterprise applications**
2. Click **New application** > **Create your own application**
3. Name it (e.g. `Aritma SCIM`) and select **Integrate any other application you don't find in the gallery**
4. Go to the **Provisioning** tab and set **Provisioning Mode** to `Automatic`
5. Under **Admin Credentials**, enter:
  - **Tenant URL**: `https://api.dev.aritma.io/core/iam/v1/scim`
  - **Secret Token**: the SCIM token from Step 1
6. Click **Test Connection** to verify
7. Click **Save**


## Step 3: Configure attribute mapping

Your identity provider maps its user attributes to SCIM attributes that Aritma understands. The standard SCIM user attributes Aritma supports include:

| SCIM attribute | Description |
|  --- | --- |
| `userName` | Unique user identifier (typically email) |
| `displayName` | Full display name |
| `emails[primary]` | Primary email address |
| `active` | Whether the user is active |
| `name.givenName` | First name |
| `name.familyName` | Last name |


For Microsoft Entra ID, the default attribute mappings are typically sufficient.

## Step 4: Assign users and groups

In your identity provider, assign users or groups to the Aritma SCIM application. Only assigned users/groups are provisioned to Aritma.

- **Microsoft Entra ID**: In the Enterprise Application, go to **Users and groups** and add the users or groups you want to sync


Once assigned, provisioning will begin on the next sync cycle (or immediately if you trigger a manual sync).

## Managing SCIM tokens

### List tokens

Note that the token value itself is never returned after creation.

### Delete a token

If a token is compromised or no longer needed, delete it immediately:

Revocation
Deleting a token immediately revokes access for any identity provider using it. The user state at token deletion will remain. If you are rotating a token, create the new token first, update your IdP configuration, then delete the old token to avoid a provisioning gap.

## SCIM and SSO

SCIM handles **provisioning** (creating/deactivating accounts). SSO handles **authentication** (logging in). They work independently but complement each other:

- SCIM alone: users are pre-created in Aritma, but still log in with Aritma ID credentials
- SSO alone: users can log in with their corporate credentials, but must be pre-invited or have auto-provisioning enabled
- SCIM + SSO: users are automatically provisioned from your directory and can log in seamlessly with their corporate credentials - the recommended setup for enterprise deployments


Tip
When using SCIM with Microsoft Entra ID, pair it with the [Azure AD SSO provider](/apis/platform/iam/sso/overview) for a fully integrated experience. Users are provisioned via SCIM and authenticate via Azure AD SSO.