SCIM provisioning with Okta

SCIM provisioning lets Okta create, update, and deactivate HiThrive users automatically as your directory changes. This guide covers the full setup, including attribute mappings that require manual configuration.

SCIM provisioning is independent of SAML SSO, though the two are usually configured together.

Before you start

Retrieve your SCIM credentials from Admin Portal > Settings > SSO in HiThrive:

• SCIM Provisioning Endpoint URL

• Secret SCIM Token

If you are also configuring SAML SSO, you will find the Entity ID, Assertion URL, and Public Key in the same location.

Part 1: App setup and provisioning

Create the Okta app integration

1. In the Okta admin console, go to Applications > Applications > Browse App Catalog

2. HiThrive is not in the Okta catalog, so click Create App Integration and choose SAML 2.0 for SSO, then layer SCIM provisioning on top. This is a custom SCIM setup rather than an OIN app

3. Navigate to the app's Provisioning tab and click Configure API Integration

4. Enter your HiThrive SCIM credentials:

1. Click Test API Credentials, then Save once the test succeeds

Enable provisioning features

Go to Provisioning > To App > Edit and enable:

• Create Users provisions new users into HiThrive

• Update User Attributes syncs profile changes

• Deactivate Users deactivates in HiThrive when a user is deactivated in Okta

💡 Leave Deactivate Users off while you are testing. Turn it on once your mappings are confirmed working.

Click Save.

Assign users

Go to Assignments and assign the users or groups that should be provisioned. Provisioning runs on assignment and then follows Okta's regular sync cycle.

Part 2: Profile Editor mapping

⚠️ Use Profile Editor, not SAML attribute statements. Attribute statements only affect SAML SSO assertions and have no effect on SCIM provisioning. All SCIM field mappings live in Directory > Profile Editor on the HiThrive app's profile. Mappings under Provisioning > To App > Attribute Mappings are downstream of what is defined there.

If anyone previously attempted to configure provisioning through attribute statements, clear those out first. Anything hardcoding active = true in particular can silently conflict with SCIM provisioning.

Standard attributes

These are usually generated automatically and correct out of the box.

externalId (required)

This is the most important mapping. Without it, provisioning pushes fail with Not Found errors because HiThrive cannot match the update to an existing record.

Okta reserves the literal name externalId, so the variable name must differ:

Map it under Provisioning > To App using this expression:

user.getInternalProperty("id")

workEmail (required)

The auto-generated email attribute typically has an incorrect external name (emails.^[primary==true].value). Delete it and create the following:

Map from user.email.

⚠️ Do not leave both email and workEmail mapped at the same time. Duplicate mappings to the same field cause conflicts.

locationCountry (optional)

Map from user.countryCode.

⚠️ The external name for this field is a HiThrive-generated field ID rather than a readable SCIM path, and it may differ per instance. Confirm the exact value with HiThrive support before configuring.

HiThrive custom fields

hire_date, birth_date, and employee_id all use the namespace urn:ietf:params:scim:schemas:extension:hithrive:1.0:User, with variable names matching the field names.

• hire_date and birth_date must be formatted YYYY-MM-DD

• Map employee_id from user.employeeNumber if you use Okta's built-in field for it

Manager

Map directly to the enterprise SCIM URN:

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager

Do not create separate custom managerValue or managerDisplayName attributes. HiThrive does not recognize those as distinct fields.

Part 3: Resolving Not Found errors on existing users

If you are layering SCIM onto users who already have HiThrive accounts, Okta pushes will fail with Invalid expression syntax or Not Found errors. This happens because HiThrive has no externalId on file to match against.

The fix is a manual import matched by email.

1. In the HiThrive app, go to Provisioning > To App and enable Import New Users and Profile Updates, with matching set to Email matches

2. Before running the import, temporarily delete any custom attribute whose external name contains brackets or quotes. This means workEmail and locationCountry. Okta's import job fails on these with Invalid expression syntax scim.<name> errors

3. Go to the Import tab and run a manual import

4. With matching set to Email matches, Okta links existing HiThrive users to existing Okta users automatically. You will see a summary such as "125 users updated"

5. Recreate workEmail and locationCountry with the settings above and remap them under Provisioning > To App

6. Test on a single user before assuming the fix worked fleet-wide. Go to Assignments > [user] > Provision User and confirm the push succeeds and the profile lands correctly in HiThrive

💡 Removing workEmail temporarily is safe as long as the legacy email attribute is still mapped to user.email. Email data continues flowing while you unblock the import.

If some users still fail after the bulk fix: their accounts likely exist in HiThrive under an internal ID that predates any Okta link. Running another manual import often picks up the remaining accounts. If not, HiThrive support can manually re-link specific accounts by internal user ID.

Known limitations

The HiThrive SCIM API does not currently support:

• SCIM Groups. Group membership does not sync, so group-based logic must be handled outside SCIM

• SCIM Bulk Updates

• PATCH operations

• Filter support in attribute mapping expressions. This is also why external names containing brackets or quotes break the import job specifically, even though they work correctly for individual push provisioning

Quick reference: full attribute map

💡 Setting up SCIM for the first time or running into errors not covered here? Contact help@hithrive.com and include the error message from Okta's provisioning log.