> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up SCIM with Microsoft Entra ID

> Connect a Microsoft Entra ID enterprise application to Living Security SCIM: token, attribute mappings, scope, a test user, and troubleshooting.

Microsoft Entra ID creates, updates and deactivates people in Living Security through SCIM. This guide connects an Entra enterprise application to Living Security and tests it with one user.

## What you need

* A Living Security admin with the **Manage Identity Provider** permission.
* Single sign-on is optional. If you use it, the SCIM `userName` must match the name your single sign-on sends. See [SSO and sub-organizations](https://docs.livingsecurity.com/features/settings/scim/sso-and-sub-organizations.md).
* If your organization already uses the earlier SCIM setup, keep your existing enterprise application. Follow [Move from the earlier SCIM setup](https://docs.livingsecurity.com/features/settings/scim/connection.md#move-from-the-earlier-scim-setup) instead of the first step below, then replace the URL and token in that enterprise application.
* In Entra: the Application Administrator or Cloud Application Administrator role. Group assignment needs Microsoft Entra ID P1 or P2.

## Set up provisioning

**1. Create the SCIM token in Living Security**

1. Open **Settings → Privacy & security → Directory sync (SCIM)**.
2. Select **Set up SCIM**.
3. Copy the **SCIM base URL** and the **Bearer token**. You can't see the token again. If you lose it, select **Rotate token**.

The token expires after one year. Living Security sends notices 30, 14, 7 and 1 days before it expires.

**2. Create the enterprise application**

In the Microsoft Entra admin center, open **Enterprise applications → New application → Create your own application**. Name it `Living Security`, select **Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**.

If you already use an enterprise application for Living Security single sign-on, you can add provisioning to it instead.

**3. Connect provisioning**

1. In the application, open **Provisioning** and set **Provisioning Mode** to **Automatic**.
2. Under **Admin Credentials**, paste the SCIM base URL into **Tenant URL** and the token into **Secret Token**.
3. Select **Test Connection**, then **Save**.

> [!TIP]
>
> The **Setup checklist** in Living Security shows **First request received** and **Connection test passed**.

**4. Map the attributes**

Open **Provisioning → Mappings → Provision Microsoft Entra ID Users** and set these mappings:

| Living Security attribute | Entra source | Notes |
| - | - | - |
| `userName` | The same attribute your single sign-on sends as NameID | **Required.** The value must be the person's email address. Use `mail`, or `userPrincipalName` only when it equals the email. Set **Match objects using this attribute** to **Yes**, matching precedence **1**. |
| `active` | Expression: `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | Deactivates a person when Entra soft-deletes or disables them. |
| `emails[type eq "work"].value` | `mail` | **Required.** People without an email are not created. |
| `name.givenName` | `givenName` | |
| `name.familyName` | `surname` | |
| `displayName` | `displayName` | |
| `title` | `jobTitle` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department` | `department` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber` | `employeeId` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager` | `manager` | Map to the enterprise `manager`, not to a custom attribute. |

Turn matching off on every other mapping.

> [!WARNING]
>
> `userName`, the single sign-on NameID and the primary email must be the same email address. If they differ, provisioning succeeds but the person can't sign in. See [Identity requirements](https://docs.livingsecurity.com/features/settings/scim/sso-and-sub-organizations.md#identity-requirements).

**5. Check your mappings**

1. In Entra, select **Show advanced options → Review your schema here** and download the schema.
2. In Living Security, open **Troubleshoot SCIM → Validate → Check an Entra mapping**.
3. Upload the file, enter the single sign-on NameID source (for example `user.userprincipalname`), and select **Check mapping**.

Fix each finding before you start provisioning. The codes are in [Mapping check codes](#mapping-check-codes).

**6. Choose who to provision**

1. In **Provisioning → Settings**, set **Scope** to **Sync only assigned users and groups**.
2. In **Users and groups**, assign the people and groups to provision.
3. Keep **Provision Microsoft Entra ID Groups** on to send groups. Each group must be security-enabled. Entra sends only the direct members of an assigned group, not members of nested groups.

**7. Test with one user**

1. Select **Provision on demand**, choose one assigned user, and select **Provision**.
2. Wait for **First user received**, then **First user ready to sign in**, on the Living Security **Setup checklist**. This takes a few minutes.
3. Ask the test user to sign in to Living Security.

> [!TIP]
>
> The checklist shows **First sign-in by a SCIM user**. If **First user ready to sign in** stays waiting, open the **Health** tab.

**8. Start provisioning**

Set **Provisioning Status** to **On** and select **Save**. Entra runs a first cycle for everyone in scope, then a cycle about every 40 minutes. A change made in Entra reaches Living Security on the next cycle. Use **Provision on demand** for one person at once.

### Living Security and custom attributes

Living Security also reads `startDate`, `location` and `employmentType` from `urn:ietf:params:scim:schemas:extension:livingsecurity:2.0:User`.

To send other attributes, select **Show advanced options → Edit attribute list for customappsso**, add an attribute such as `urn:ietf:params:scim:schemas:extension:yourcompany:2.0:User:costCenter`, then map it. Living Security stores custom extension attributes and lists them in its `/Schemas` document. Limits: 20 custom extension schemas, 200 attributes per schema, 256-character schema URNs.

### Restart provisioning

**Restart provisioning** clears Entra's state and runs a full cycle again. Living Security matches each user on `userName`, so a restart creates no duplicates.

## Troubleshoot

Open **Settings → Privacy & security → Directory sync (SCIM) → Troubleshoot**. The **Health** tab shows failed requests, held accounts and token expiry. The **Attributes** tab shows what your identity provider sends. **Copy diagnostics** copies request IDs and error codes for a support request, with no names, emails or tokens.

### Quarantine

Entra puts the application in quarantine when most of its requests fail, and then runs cycles less often. The **Health** tab shows **Quarantine risk** before this happens.

**1. Find the cause**

Read the error in Entra's **Provisioning logs** and fix the cause. An expired or revoked token (`LS-SCIM-1001`) is the usual cause.

**2. Leave quarantine**

Select **Restart provisioning**.

### Attribute problems

The **Attributes** tab shows what Entra sent for the newest user, how many people carry each attribute, and attributes Living Security did not store. Fix each finding in **Provisioning → Mappings → Provision Microsoft Entra ID Users**, then select **Provision on demand** for one user to check it.

| Finding | Fix in Entra |
| - | - |
| userName is not an email | Map `userName` from `mail`, or from `userPrincipalName` only when it equals the email. Use the same source as the single sign-on NameID. |
| userName differs from the email | Map `userName` and `emails[type eq "work"].value` from the same source, usually `mail`. |
| Email missing | Map `mail` to `emails[type eq "work"].value`. |
| active not sent | Map `active` with `Switch([IsSoftDeleted], , "False", "True", "True", "False")`. |
| Attribute sent without its schema | Edit the target attribute. Use the full schema path, for example `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`, not `department`. Entra lists the full paths in **Show advanced options → Edit attribute list for customappsso**. |
| Attribute not stored | The target is not a SCIM attribute. Map it to a declared attribute or to a custom extension, as in [Living Security and custom attributes](#living-security-and-custom-attributes). |
| Attribute not sent | No person has a value. Add the mapping from the table in **Map the attributes**, and check that the Entra source has values. |
| userName changed | Changing the source of `userName` changes everyone's sign-in name. Keep `userName` on the single sign-on NameID source. |

### Error codes

Each failed request has an `LS-SCIM` code in its error detail. Entra shows it in the **Provisioning logs**.

| Code | Meaning | Fix |
| - | - | - |
| `LS-SCIM-1001` | Authentication failed | Copy the SCIM base URL and a current token from the SCIM card into **Tenant URL** and **Secret Token**. A token from another region also fails. |
| `LS-SCIM-1103` | Required attribute missing | Map `userName` for users and `displayName` for groups. |
| `LS-SCIM-1104` | Invalid attribute value | Correct the mapping so the value has the declared type. |
| `LS-SCIM-1107` | No usable email | Map `mail` to `emails[type eq "work"].value`. |
| `LS-SCIM-1108` | More than one primary email | Mark exactly one email as primary. |
| `LS-SCIM-1112` | Extension too large | Stay inside the custom attribute limits above. |
| `LS-SCIM-1201` | `userName` already in use | Two Entra users map to the same `userName`. Give each a unique one. |
| `LS-SCIM-1401` | Invalid PATCH path | Map to an attribute that `/Schemas` lists. |
| `LS-SCIM-1601` | Rate limited | No action. Entra retries. |
| `LS-SCIM-1602` | Changes paused | No action. Entra retries. |
| `LS-SCIM-1604` | Internal error | Retry. If it continues, contact Living Security Support with the diagnostics. |

### Held accounts

Some changes are accepted but held. Entra shows success, the SCIM card shows **Held accounts**, and the **Health** tab lists each reason with its fix. Fix the cause, then select **Provision on demand** for the person: the next change applies. If an account stays held, contact Living Security Support with the diagnostics.

| Code | Meaning | Fix |
| - | - | - |
| `LS-SCIM-1501` | Held: last owner | The change would remove the last owner. Make another person an owner. |
| `LS-SCIM-1502` | Held: excluded from sync | Remove the exclusion on the person's record. |
| `LS-SCIM-1503` | Held: ambiguous person | Merge or correct the duplicate person records. |

### Mapping check codes

| Code | Finding | Fix |
| - | - | - |
| `LS-SCIM-1701` | No user mappings found | Download the schema from **Review your schema here** and upload the whole file. |
| `LS-SCIM-1702` | Wrong matching attribute | Set matching precedence 1 on `userName` and turn matching off on other mappings. |
| `LS-SCIM-1703` | `userName` differs from the single sign-on name | Map `userName` from the NameID source attribute. |
| `LS-SCIM-1704` | `active` does not follow deletion | Use the `Switch([IsSoftDeleted], …)` expression above. |
| `LS-SCIM-1705` | No work email mapping | Map `mail` to `emails[type eq "work"].value`. |
| `LS-SCIM-1706` | Manager not mapped to the enterprise extension | Map `manager` to the enterprise `manager` attribute. |
| `LS-SCIM-1707` | Mapping to an attribute Living Security does not use | Map to a core, enterprise or Living Security attribute, or remove the mapping. |

## Related

> [card] [SCIM provisioning](https://docs.livingsecurity.com/features/settings/scim.md)
>
> Identity rules, directory groups and request history.

> [card] [Set up SCIM with Okta](https://docs.livingsecurity.com/features/settings/scim-okta.md)
>
> The same setup for Okta.


## Related topics

- [Set up SCIM with Okta](https://docs.livingsecurity.com/features/settings/scim-okta.md)
- [Set up a SCIM connection](https://docs.livingsecurity.com/features/settings/scim/connection.md)
- [SCIM groups and cohorts](https://docs.livingsecurity.com/features/settings/scim/groups.md)


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