# SCIM Provisioning

### Overview

With Heeler, you can automate user lifecycle management using an Identity Provider (IdP) that supports SCIM 2.0 (System for Cross-domain Identity Management), such as Okta or Microsoft Entra ID.

SCIM provisioning works alongside SAML SSO to provide complete identity lifecycle management. While SAML handles authentication (how users log in), SCIM handles provisioning (how user accounts are created, updated, and removed). When an employee is removed from your IdP, SCIM automatically deactivates their Heeler account, destroys all active sessions, and revokes API tokens — ensuring access is revoked immediately without manual intervention.

{% hint style="info" %}
SCIM provisioning requires that SAML SSO is configured first. Users provisioned via SCIM are created with SAML enabled and authenticate through your Identity Provider.
{% endhint %}

### Requirements

* SAML SSO configured and working (see SAML Setup)
* An Identity Provider that supports SCIM 2.0 (Okta, Microsoft Entra ID, or similar)
* Heeler administrator access to generate SCIM tokens

### Heeler Setup

#### Step 1: Navigate to SCIM Provisioning

Navigate to **Administration** → **Access** → **SCIM Provisioning** from the sidebar.

#### Step 2: Copy the SCIM Endpoint URL

The SCIM endpoint URL is displayed at the top of the page. Copy this URL — you will need it when configuring your Identity Provider.

The endpoint URL follows the format: `https://<your-heeler-domain>/api/scim/v2`

#### Step 3: Generate a Bearer Token

1. Enter a descriptive name for the token (e.g., "Okta SCIM" or "Entra ID Provisioning")
2. Click **Generate Token**
3. **Copy the token immediately** — it will only be displayed once and cannot be retrieved later

{% hint style="warning" %}
Store the bearer token securely. If you lose it, you will need to generate a new token and update your IdP configuration.
{% endhint %}

#### Step 4: Configure Your Identity Provider

Use the SCIM endpoint URL and bearer token to configure provisioning in your IdP. See the provider-specific instructions below.

### Identity Provider Setup

{% tabs %}
{% tab title="Okta" %}

#### Okta SCIM Configuration

1. In your Okta admin console, go to **Applications** and select your Heeler application
2. Go to the **Provisioning** tab and click **Configure API Integration**
3. Check **Enable API Integration**
4. Set the **SCIM connector base URL** to the endpoint URL from Heeler (e.g., `https://app.heeler.ai/api/scim/v2`)
5. Set **Authentication Mode** to **HTTP Header**
6. Paste the bearer token from Heeler into the **Authorization** field (enter the full token including the `h4r-scim-` prefix)
7. Click **Test API Credentials** to verify the connection
8. Click **Save**

**Enable Provisioning Features**

After saving the API integration:

1. Go to **Provisioning** → **To App**
2. Click **Edit** and enable the following:
   * **Create Users** — Automatically create Heeler accounts when users are assigned
   * **Update User Attributes** — Sync name changes from Okta to Heeler
   * **Deactivate Users** — Automatically deactivate Heeler accounts when users are unassigned or deactivated in Okta

**Attribute Mapping**

Okta maps the following attributes to Heeler automatically:

| Okta Attribute | SCIM Attribute    | Heeler Field   |
| -------------- | ----------------- | -------------- |
| `userName`     | `userName`        | Email address  |
| `givenName`    | `name.givenName`  | First name     |
| `familyName`   | `name.familyName` | Last name      |
| `active`       | `active`          | Account status |
| {% endtab %}   |                   |                |

{% tab title="Microsoft Entra ID" %}

#### Microsoft Entra ID (Azure AD) Configuration

1. In the Azure Portal, go to **Microsoft Entra ID** → **Enterprise Applications**
2. Select your Heeler application (or create one if you haven't already)
3. Go to **Provisioning** and click **Get started**
4. Set **Provisioning Mode** to **Automatic**
5. Under **Admin Credentials**:
   * Set **Tenant URL** to the endpoint URL from Heeler (e.g., `https://app.heeler.ai/api/scim/v2`)
   * Set **Secret Token** to the bearer token from Heeler
6. Click **Test Connection** to verify the connection
7. Click **Save**

**Configure Attribute Mappings**

Under **Provisioning** → **Mappings**:

1. Click **Provision Microsoft Entra ID Users**
2. Verify the following mappings are configured:

| Entra ID Attribute                                           | SCIM Attribute    | Heeler Field   |
| ------------------------------------------------------------ | ----------------- | -------------- |
| `userPrincipalName`                                          | `userName`        | Email address  |
| `givenName`                                                  | `name.givenName`  | First name     |
| `surname`                                                    | `name.familyName` | Last name      |
| `Switch([IsSoftDeleted],, "False", "True", "True", "False")` | `active`          | Account status |

3. Click **Save**

**Start Provisioning**

1. Return to the **Provisioning** overview page
2. Set **Provisioning Status** to **On**
3. Click **Save** to start the initial provisioning cycle

{% hint style="info" %}
Entra ID runs an initial provisioning cycle that may take several minutes depending on the number of users in scope. Subsequent incremental cycles run approximately every 40 minutes.
{% endhint %}
{% endtab %}
{% endtabs %}

### Managing SCIM Tokens

#### Viewing Active Tokens

The SCIM Provisioning page displays all tokens for your tenant, showing the token name, a prefix identifier, creation date, and status (Active or Revoked).

#### Revoking a Token

To revoke a SCIM token:

1. Click the delete icon next to the token
2. Confirm the revocation in the dialog

{% hint style="warning" %}
Revoking a token immediately prevents your IdP from making SCIM requests. User provisioning and deprovisioning will stop until a new token is configured in your IdP.
{% endhint %}

#### Rotating Tokens

To rotate a SCIM token:

1. Generate a new token in Heeler
2. Update the token in your IdP configuration
3. Verify the connection using your IdP's test feature
4. Revoke the old token in Heeler

### How SCIM Interacts with SAML

| Scenario                             | Behavior                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------- |
| User assigned in IdP                 | SCIM creates user in Heeler with SAML enabled                             |
| User logs in                         | SAML authenticates the user via your IdP                                  |
| User attributes change in IdP        | SCIM syncs first name, last name to Heeler                                |
| User removed from IdP                | SCIM deactivates user, destroys sessions, revokes API tokens              |
| SCIM active + SAML JIT enabled       | SCIM takes precedence — JIT provisioning is disabled to prevent conflicts |
| Deactivated user attempts SAML login | Login is rejected even if IdP session is still valid                      |

### Supported SCIM Features

| Feature                                           | Supported                               |
| ------------------------------------------------- | --------------------------------------- |
| User provisioning (create)                        | ✅                                       |
| User deprovisioning (deactivate)                  | ✅                                       |
| User attribute sync (update)                      | ✅                                       |
| Filter users (`userName`, `externalId`, `active`) | ✅                                       |
| Group provisioning                                | ❌ (Heeler Teams are managed separately) |
| Bulk operations                                   | ❌                                       |
| Password sync                                     | ❌ (SAML users authenticate via IdP)     |