Set up SCIM with Okta - Living Security Platform

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.
If your organization already uses the earlier SCIM setup, keep your existing app integration. Follow 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

Create the SCIM token in Living Security

Open Settings → Privacy & security → Directory sync (SCIM).
Select Set up SCIM.
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.

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.

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

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.

The SCIM card issues bearer tokens, so use HTTP Header. Basic Auth is not available from the SCIM card.

The Setup checklist in Living Security shows First request received and Connection test passed.

Turn on provisioning features

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

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.

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.

Test with one user

In Assignments, assign one test user to the app. Okta pushes the user at once.
Wait for First user received, then First user ready to sign in, on the Living Security Setup checklist. This takes a few minutes.
Ask the test user to sign in to Living Security.

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

SCIM provisioning

Identity rules, directory groups and request history.

Set up SCIM with Microsoft Entra ID

The same setup for Microsoft Entra ID.

Settings

What you need

Set up provisioning

Living Security and custom attributes

Assign people and push groups

Deactivation

Troubleshoot

Attribute problems

Error codes

Held accounts

Related

SCIM provisioning

Set up SCIM with Microsoft Entra ID