> ## 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 Okta

> Connect an Okta app integration to Living Security SCIM: token, provisioning features, profile mappings, assignments, group push, and troubleshooting.

Okta creates, updates and deactivates people in Living Security through SCIM 2.0. This guide connects an Okta app integration 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 app integration. 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 app integration.
* An Okta Super Administrator or Application Administrator.

## 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. Turn on SCIM in the app integration**

Okta adds SCIM provisioning only to SAML 2.0 and SWA app integrations. Use the SAML app integration you use for Living Security single sign-on. If you sign in with OIDC, create a separate SAML or SWA app integration for provisioning in **Applications → Applications → Create App Integration**.

1. In the app, open **General → App Settings → Edit**.
2. Set **Provisioning** to **SCIM** and select **Save**. A **Provisioning** tab appears.

**3. Connect provisioning**

In **Provisioning → Integration**, select **Edit** and set:

| Okta field | Value |
| - | - |
| SCIM connector base URL | The SCIM base URL from the SCIM card |
| Unique identifier field for users | `userName` |
| Supported provisioning actions | **Import New Users and Profile Updates**, **Push New Users**, **Push Profile Updates**, **Push Groups** |
| Authentication Mode | **HTTP Header** |
| Authorization | The bearer token from the SCIM card |

Select **Test Connector Configuration**, then **Save**.

> [!NOTE]
>
> The SCIM card issues bearer tokens, so use **HTTP Header**. **Basic Auth** is not available from the SCIM card.

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

**4. Turn on provisioning features**

In **Provisioning → To App**, select **Edit**, turn on **Create Users**, **Update User Attributes** and **Deactivate Users**, and select **Save**.

**5. Map the profile**

In **Provisioning → To App → Attribute Mappings**, check these mappings. Edit them in **Go to Profile Editor** when needed.

| Living Security attribute | Okta source | Notes |
| - | - | - |
| `userName` | Okta username (`user.login`) | **Required.** Set by the app's **Application username format**. The value must be the person's email address and match the single sign-on username. |
| `emails[type eq "work"].value` | `user.email` | **Required.** People without an email are not created. |
| `name.givenName` | `user.firstName` | |
| `name.familyName` | `user.lastName` | |
| `displayName` | `user.displayName` | |
| `title` | `user.title` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department` | `user.department` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber` | `user.employeeNumber` | |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager` | `user.managerId` | |

Okta sets `active` itself. Do not map it.

> [!WARNING]
>
> `userName`, the single sign-on username 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).

**6. Test with one user**

1. In **Assignments**, assign one test user to the app. Okta pushes the user at once.
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.

### 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 them or other attributes, add them in the Profile Editor with that schema URN, or your own `urn:ietf:params:scim:schemas:extension:yourcompany:2.0:User` URN. Limits: 20 custom extension schemas, 200 attributes per schema, 256-character schema URNs.

## Assign people and push groups

* **Assign.** In **Assignments**, assign the people or groups to provision. Okta pushes each assignment and each profile change at once.
* **Push groups.** In **Push Groups**, select **Push Groups → Find groups by name**, choose a group and select **Save**. Use different groups for **Assignments** and **Push Groups**. Okta doesn't support one group for both.
* **Import.** In **Import**, select **Import Now** to read the people Living Security already has and match them to Okta users. Import reads only; it changes nothing in Living Security.

## Deactivation

| Okta action | Result in Living Security |
| - | - |
| Unassign a user from the app | The person is deactivated. |
| Deactivate the user in Okta | The person is deactivated. |
| Suspend the user in Okta | **No change.** Okta keeps the assignment and sends nothing. To remove access, deactivate or unassign the user. |
| Assign or reactivate the user again | The person is reactivated with their history. |
| Delete the user in Okta | Okta deactivates first. The person stays deactivated. |

A deactivation is held, and the person stays active, only when it would remove the last owner (`LS-SCIM-1501`). Make another person an owner first.

## 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.

In Okta, failed pushes show in **Dashboard → Tasks** and in the **System Log**. Each failed request has an `LS-SCIM` code in its error detail. After you fix the cause, select **Retry Selected** on the task, or push the user again.

### Attribute problems

The **Attributes** tab shows what Okta sent for the newest user, how many people carry each attribute, and attributes Living Security did not store. Fix each finding in **Provisioning → To App → Attribute Mappings** or the **Profile Editor**, then push one user again to check it.

| Finding | Fix in Okta |
| - | - |
| userName is not an email | Set **General → App Settings → Application username format** to **Email**, so the Okta username sent as `userName` is the email address. |
| userName differs from the email | Map `userName` and `emails[type eq "work"].value` from the same value, usually `user.email`. |
| Email missing | Map `user.email` to `emails[type eq "work"].value`. |
| active not sent | Turn on **Deactivate Users** in **Provisioning → To App**. Okta sends `active` itself. |
| Attribute sent without its schema | In the **Profile Editor**, edit the app attribute and set its external namespace to the full schema URN, for example `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` for `department`. |
| Attribute not stored | The app attribute is not a SCIM attribute. Use a declared attribute or 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 profile**, and check that the Okta profile has values. |
| userName changed | A changed **Application username format** changes everyone's sign-in name. Keep it on the single sign-on username. |

### Error codes

| Code | Meaning | Fix |
| - | - | - |
| `LS-SCIM-1001` | Authentication failed | Copy the SCIM base URL and a current token from the SCIM card into the **Integration** settings. A token from another region also fails. |
| `LS-SCIM-1103` | Required attribute missing | Map `userName` for users. Give each pushed group a name. |
| `LS-SCIM-1104` | Invalid attribute value | Correct the Profile Editor mapping so the value has the declared type. |
| `LS-SCIM-1107` | No usable email | Map `user.email` to the work email. |
| `LS-SCIM-1108` | More than one primary email | Mark exactly one email as primary. |
| `LS-SCIM-1109` | Resource not found | The user or group was deleted in Living Security. Push it again to create it. |
| `LS-SCIM-1112` | Extension too large | Stay inside the custom attribute limits above. |
| `LS-SCIM-1201` | `userName` already in use | Two Okta users have the same username. Give each a unique one. |
| `LS-SCIM-1601` | Rate limited | No action. Okta retries. |
| `LS-SCIM-1602` | Changes paused | No action. Okta 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. Okta shows success, the SCIM card shows **Held accounts**, and the **Health** tab lists each reason with its fix. Fix the cause, then push the person again: 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. |

## Related

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

> [card] [Set up SCIM with Microsoft Entra ID](https://docs.livingsecurity.com/features/settings/scim-microsoft-entra-id.md)
>
> The same setup for Microsoft Entra ID.


## Related topics

- [Set up SCIM with Microsoft Entra ID](https://docs.livingsecurity.com/features/settings/scim-microsoft-entra-id.md)
- [Set up a SCIM connection](https://docs.livingsecurity.com/features/settings/scim/connection.md)
- [Set up SCIM with another SCIM 2.0 client](https://docs.livingsecurity.com/features/settings/scim-generic.md)


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