WorkOS Docs Homepage
Integrations
DashboardSign In

Okta SCIM

Learn about syncing your user list with Okta SCIM.

This guide outlines how to synchronize your application’s Okta directories using SCIM.

To synchronize an organization’s users and groups provisioned for your application, you’ll need to provide the organization with two pieces of information:

  • An Endpoint that Okta will make requests to.
  • A Bearer Token for Okta to authenticate its endpoint requests.

After completing step 1 below, both of these are available in your Endpoint’s Settings in the WorkOS Dashboard.

The rest of the steps below will need to be carried out by the organization when configuring your application in their Okta instance.

Login to your WorkOS Dashboard and select “Organizations” from the left hand navigation bar.

Select the organization you’ll be configuring a new Directory Sync with.

Click “Add Directory”.

A screenshot showing where to click "Add Directory" in the WorkOS dashboard.

Select “Okta” from the Directory Provider dropdown and provide the Name for the Directory Sync connection. Then, click “Create Directory”.

A screenshot showing where to name and create an Okta directory in the WorkOS dashboard.

You’ll see WorkOS has created the Endpoint and Bearer Token which you will provide to Okta in the steps below.

A screenshot showing the Okta directory details in the WorkOS dashboard.

We have support for custom labeled URLs for Directory Sync endpoints. Contact us for more info!

Log in to Okta, go to the Okta admin dashboard and select “Applications” in the navigation bar.

A screenshot showing where to select "Applications" in Okta.

If your application is already created, select it from the list of applications and move to Step 3.

A screenshot showing where to select an already created application in Okta.

If you haven’t created a SAML application in Okta, select “Browse App Catalog”.

A screenshot showing where to select "Browse App Catalog" in Okta.

From your Okta Application dashboard, search for “SCIM 2.0 Test App (Oauth Bearer Token)” and select the corresponding result.

A screenshot showing where to search for "SCIM 2.0 Test App (OAuth Bearer Token)" in the App Integration Catalog in Okta.

On the following page, click “Add Integration”.

A screnshot showing where to click "Add" in the SCIM 2.0 Test App (OAuth Bearer Token) overview page in Okta.

Enter a descriptive App name, then click “Next”.

A screenshot showing where to enter a name in the "Application label" field in Okta.

Many applications will work with the default configuration that is set on your new application. If you require any additional configuration for your directory such as configuring Attribute Statements, do so on the Sign-On Options page. Click “Done” to complete creating your application.

In your application’s Enterprise Okta admin panel, click the “Provisioning” tab. Then, click “Configure API Integration”.

A screenshot showing where to navigate to the "Provisioning" tab to click "Configure API Integration" in Okta.

Check “Enable API Integration”. After that, copy and paste the Endpoint from your WorkOS Dashboard in the SCIM 2.0 Base URL field.

Then, copy and paste the Bearer Token from your WorkOS Dashboard into the OAuth Bearer Token field.

Click “Test API Credentials”, and then click “Save”.

A screenshot showing where to configure the provisioning credentials in the "Provisioning" tab in Okta.

The provisioning tab will now show a new suite of options which we’ll utilize in the next Guide Section to continue provisioning your application.

In the “To App” navigation section, check to enable:

  • Create Users
  • Update User Attributes
  • Deactivate Users

Click “Save”.

A screenshot showing where to enable "Create Users", "Update User Attributes", and "Deactivate Users" in the "To App" tab in Okta.

To assign users to the SAML Application, navigate to the “Assignments” tab, from the “Assign” dropdown, select “Assign to People”.

A screenshot showing where to select "Assign to People" in the "Assign" dropdown in the "Assignments" tab in Okta.

Select users you’d like to provision and select “Assign”.

A screenshot showing where to select "Assign" for specific users in Okta.

When you click “Assign” a lengthy form will open where you can populate all of the user’s metadata. Confirm the metadata fields, scroll down to the bottom, and press “Save and Go Back”. Repeat this for all users and select “Done”.

A screenshot showing where to select "Save and Go Back" to complete user assignment in Okta.

To push groups in order to sync group membership, navigate to the “Push Groups” tab, from the “Push Groups” dropdown, select: “Find groups by name”.

Caution: Okta advises using separate groups for push groups and group assignments. Otherwise, memberships won't be accurately reflected without manual group pushes for membership changes.

A screenshot showing where to select "Find groups by name" in the "Push Groups" dropdown in the "Push Groups" tab in Okta.

Search for the group you’d like to push and select it. Make sure the box is checked for “Push Immediately” and click “Save”.

A screenshot showing where to search for groups to push in the "Push Groups" tab in Okta.

In the WorkOS dashboard, you should now see the users and groups synced over.

A screenshot showing a successfully synced user from an Okta directory in the WorkOS dashboard.

A detailed guide to integrate the WorkOS API with your application can be found here

When a user is assigned to the SCIM app via a group, I don’t see a user removed webhook if the user is removed from the group – is this expected?

It is a known issue with Okta SCIM that if a user is assigned to a SCIM app via a group, you won’t see a dsync.group.user_removed event if the user is removed from the group. This is a limitation in Okta, where group memberships are not updated in this case. The user needs to be assigned directly to the SCIM app, and the group needs to be pushed in the SCIM app. If those two conditions are met, Okta will send the correct group membership updates.

How often do the Okta SCIM 2.0 directories perform a sync?

The Okta SCIM 2.0 directory syncs events in real time.

Why is a user suspended in Okta still active in WorkOS?

Suspending a User in Okta will only affect their login and will not alter their status in any connected applications.

Deactivating or Deleting a User in Okta will result in a inactive status in connected applications (i.e., WorkOS).

For more details, please refer to Okta's official documentation User Suspension User Deactivation and Deletion.