# Set up SCIM with Okta > Step-by-step guide to configure SCIM provisioning between Okta and Holistics These are instructions for setting up Holistics SCIM provisioning with Okta. If you use a different identity provider and need assistance with configuration, please [contact our support team](mailto:support@holistics.io). ## Before you begin :::info Prerequisites - **SAML SSO with Okta configured**: You must have [SAML SSO with Okta](/docs/authentication/sso/okta) set up before enabling SCIM. - **SCIM enabled in Holistics**: Follow [Step 1](/docs/authentication/sso/scim#step-1-enable-scim-provisioning) and [Step 2](/docs/authentication/sso/scim#step-2-configure-group-to-role-mapping) in the SCIM provisioning guide to enable SCIM and configure group-to-role mapping. - **SCIM Base URL and API Token ready**: Copy the **SCIM Base URL** and **SCIM API Token** from Holistics. You'll need them to configure Okta. - **Admin access**: You must be an Administrator in both Holistics and Okta. ::: :::warning Important Set up [group-to-role mapping](/docs/authentication/sso/scim#step-2-configure-group-to-role-mapping) (at least for the Admin role) **before** configuring SCIM in Okta. Otherwise, all synced users (including current admins) will default to the Viewer role, which could lock you out. ::: ## Step 1: enable SCIM in Okta 1. In the Okta admin console, open your Holistics application. 2. Go to the **General** tab. 3. Under **Provisioning**, select **SCIM**. 4. Click **Save**. ## Step 2: configure the SCIM connection 1. Go to the **Provisioning** tab of your Holistics app. 2. Under **Settings > Integration**, click **Edit**. 3. Fill in the following fields: - **SCIM connector base URL**: Enter the **SCIM Base URL** from Holistics. - **Unique identifier field for users**: Enter `email`. - **Supported provisioning actions**: Enable the following: - Push New Users - Push Profile Updates - Push Groups - **Authentication Mode**: Select **HTTP Header**. 4. Under **HTTP Header**, paste the **SCIM API Token** from Holistics into the **Authorization** field. 5. Click **Test Connector Configuration** to verify the connection. 6. Click **Save**. :::warning The SCIM API Token is only displayed once when you generate it in Holistics. If you lose it, you'll need to generate a new one, which will invalidate the previous token. ::: ## Step 3: enable provisioning to app 1. In the **Provisioning** tab, go to **Settings > To App**. 2. Click **Edit** and enable the following: - **Create Users** - **Update User Attributes** - **Deactivate Users** 3. Click **Save**. ## Step 4: configure attribute mappings Still in the **To App** section, scroll down to the attribute mappings. Make sure the following attributes are mapped correctly: | Okta attribute | Holistics field | Notes | |----------------|-----------------|-------| | `email` | Email address | Used as the unique identifier | | `displayName` | Name | Displayed in Holistics | ## Step 5: assign users to Holistics Once SCIM is configured, you can start assigning users. :::tip Best practice: Roll out in phases Assign a small pilot group first (a handful of users or one test group) and confirm they sync correctly in Holistics with the right roles. Once you are confident, assign the rest of your organization. ::: 1. In Okta, open your Holistics application. 2. Go to the **Assignments** tab. 3. Click **Assign** > **Assign to People** or **Assign to Groups**. 4. Select the users or groups you want to add. 5. Review their profile attributes and click **Save and Go Back**. 6. Click **Done**. All assigned users will be synced from Okta to Holistics. To deactivate a user, unassign them from the Holistics app in Okta. They will be deactivated (not deleted) in Holistics. ## Step 6: push groups to Holistics Groups help you manage permissions at scale. Instead of assigning access to individual users, you can assign it to a group and let SCIM handle the membership. 1. In Okta, open your Holistics application. 2. Go to the **Push Groups** tab. 3. Click **Push Groups** > **Find groups by name**. 4. Search for and select the group you want to push. 5. Click **Save**. The group and its members will be synced to Holistics. :::warning Users in pushed groups must also be assigned to the Holistics app. Pushing a group alone does not assign its members (make sure each user is individually assigned or assigned through a group in the **Assignments** tab). ::: ## Verify the setup After completing the steps above: 1. Check the **User Management** page in Holistics to confirm that synced users appear with the correct roles. 2. In Okta, go to **Reports > System Log** and filter for provisioning events to verify that sync operations completed successfully. Provisioning users and groups may take a few moments. If changes don't appear right away, wait a minute and refresh. ## Troubleshooting ### Users aren't syncing to Holistics 1. **Check the API connection**: In Okta, go to **Provisioning > Integration** and click **Test API Credentials**. 2. **Verify the token**: If the test fails, generate a new SCIM API Token in Holistics and update it in Okta. 3. **Check Okta's system log**: Go to **Reports > System Log** and filter for provisioning events to see error details. 4. **Confirm user assignment**: Make sure the user is actually assigned to the Holistics app in Okta. 5. **Check seat limit**: Provisioning fails if adding the user would exceed your Holistics seat limit. ### Groups aren't appearing in Holistics 1. **Check Push Groups status**: In Okta's **Push Groups** tab, verify the group shows as "Active". 2. **Review the system log**: Look for any errors related to group push operations. 3. **Wait for sync**: Group changes can take a few minutes to propagate. ### User profile changes aren't updating 1. **Verify "Update User Attributes" is enabled**: Check Okta's **Provisioning > To App** settings. 2. **Check the attribute mapping**: Ensure the attributes you're changing are included in the attribute mappings. 3. **Trigger a manual sync**: In Okta, you can force a sync by unassigning and reassigning the user.