WorkOS Docs Homepage

Okta SCIM v1.1

Learn about syncing your user list with Okta SCIM v1.1.

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

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

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

Both of these are available in your Endpoint’s Settings in the WorkOS Dashboard.

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

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

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

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.

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

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

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

On the following page, click “Add”.

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

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

Check “Enable API Integration”. After that, copy and paste the Endpoint from your WorkOS Dashboard in the SCIM 1.1 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”.

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

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

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

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

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

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