Configuring SCIM Provisioning with Okta

Have an enterprise account set up in WorkRamp and have access to an admin user account.

Follow the steps here to generate your API token.

Navigate to the "Applications" tab in your Okta admin dashboard, then the "Applications" subtab, then click "Browse App Catalog".

Enter "workramp" in the search bar, click the matching result, and click "Add Integration" on the page that comes up.

On the next screen, select a label for the application, select your region (if you don't know, select "US (default)"), and click "Done".

After you click the "Done" button, the WorkRamp application will be added to your account. The "Assignments" configuration section of the WorkRamp application will be selected. From here, click the "Provisioning" tab.

Click the "Configure API Integration" button.

Check the "Enable API Integration" checkbox. Enter the API token that you received from from the integrations tab. Test the credentials using the provided button, then click the "Save" button.

After clicking "Save", the API integration should be successfully enabled. You should still be redirected to the "To App" subtab of "Provisioning". This is where you'll configure the settings for syncing users and attributes from Okta to WorkRamp. Click the "Edit" button.

Now click the checkbox next to "Enable" under the sections "Create Users", "Update User Attributes'" and "Deactivate Users". The descriptions summarize the functionality of each setting. Then click the "Save" button.

From the "Provisioning" tab select the "To Okta" subtab. This is where you'll configure the settings for syncing users from WorkRamp to Okta.

Scroll down to the "User Creation & Matching" section and click the "Edit" button.

Make sure the "Okta username format matches" option is selected (and optionally "Partial match on first and last name"), then click the "Save" button.

Everything should now be set up and the SCIM integration will be enabled. If needed, you can now assign any users/groups to the WorkRamp application from the "Assignments" tab. (See section "Group sync configuration" and subsection "Fully-automated group sync" for instructions for automatically syncing users to WorkRamp via Okta groups.)

If SCIM is being set up during the initial deployment of WorkRamp, then you are done and no additional steps need to be taken. If SCIM is being set up after the initial deployment of WorkRamp (and users already exist in the WorkRamp application), we will need to take a few additional steps in order for SCIM to work for existing users. Because these users already exist and were not originally provisioned through SCIM, we need to "reset" a mapping on the Okta side:

Navigate to the "Push Groups" tab from the WorkRamp application in Okta and then click the "Push Groups" button. From the dropdown select "Find groups by name".

Enter the Okta group name you want to sync to WorkRamp in the text field and select it from the dropdown menu.

Depending on whether a group with the same name already exists in WorkRamp, you will either see (a) "Match found"; or (b) "No match found" and the options to create a new WorkRamp group or link an existing WorkRamp group. Choose the appropriate option, then press the "Save" button.

Matching group does not exist:

You should now see that the group was added and marked as "Active". The group will have been created in WorkRamp and any current users that are part of the group (that have also been assigned the WorkRamp application) will be added to that group in WorkRamp.

Now, whenever a new user in the synced group is manually assigned to the WorkRamp application in Okta, their account will be created in WorkRamp and they will also be added to the group in WorkRamp. If you want to fully automate this process, continue with the instructions below. Otherwise, setup is now complete.

Instead of manually assigning users to the WorkRamp application, you can assign a group. As soon as users are added to a group, they will be automatically assigned the WorkRamp application, their account will be created in WorkRamp, and they will be added to the linked group in WorkRamp.

Note that if you assign a group to the WorkRamp application in Okta, WorkRamp will create an account for every user (who doesn't already have a WorkRamp account) in that group right away. To proceed, click the "Assignments" tab in WorkRamp, click the "Assign" button, then select "Assign to Groups".

Enter the group name in the text field, click the "Assign" button, then click the "Done" button. You can select the built-in "Everyone" group to sync all Okta users in your organization.

Navigate to the "Provisioning" tab and the "To App" subtab in the WorkRamp application in Okta. Scroll down to the "WorkRamp Attribute Mappings" section and click "Show Unmapped Attributes".

If you see the "Manager Name" attribute, you can skip ahead to Step 5 below. Otherwise, we will have to create the attribute manually. In order to do this, click "Go to Profile Editor" (see above screenshot).

From the profile editor page, click "Add Attribute".

Fill out the form that pops up with the following values and click "Save":

Navigate back to the application "Provisioning" tab, "To App" subtab, and scroll down to the "WorkRamp Attribute Mappings" section. Click the Edit icon next to the "Manager Name" attribute.

From here, select "Map from Okta profile" and then select the appropriate attribute from the Okta user profile that corresponds to the manager. A preview should automatically be displayed for a user from your organization. If the manager is set in Okta and the custom attribute is configured correctly (more details here), this attribute should be the manager's full name as a string in the following format: "FirstName LastName" (for example: "Judy Johnson"). For "Apply on", you will probably want to select "Create and update" so that updates will be pushed.

If your manager information is set in Okta and mapping correctly, you're done! If you want to manually set a manager for a particular user, then please keep following these instructions. Select the "People" subtab from the "Directory" tab.

Search for a user by typing their name or email address in the search bar. Then click their name in the results in order to edit their profile.

Select the "Profile" tab and click the "Edit" button.

Scroll down to the "Manager" field and enter the full name of the user's manager. Note that this name should be an exact match with the name of an existing user in Okta. Now, when this user is assigned the WorkRamp application, they will be created in WorkRamp and their manager will be set correctly.

You will first need to create a custom attribute in WorkRamp. See this Help article on how to do so. Take note of the "API Name" of the custom attribute you have created. We'll be using this when configuring the custom attribute in Okta.

Navigate to the "Provisioning" tab and the "To App" subtab in the WorkRamp application in Okta. Scroll down on this page until you reach the Attribute Mappings section and click "Go To Profile Editor".

Click the "Add Attribute" button.

Enter the following values in the popup modal:

Now go back to the "Attribute Mappings" section under the "Provisioning" tab (from Step 2) and click "Show Unmapped Attributes".

Next to the custom attribute we just added, click the Edit icon.

From here, you can set how the custom attribute is populated. Generally you will want to map the attribute from the user's Okta profile. Also, be sure to select the "Create and update" option for the "Apply on" setting. A preview of this value for a user in your organization will be displayed. Click "Save".

After this is all set up, you might have to click the "Force Sync" button to get the attribute to update for existing users.

You can view a user's value for each custom attribute in WorkRamp by going to the "Users" page under "Settings". Click the "Show custom fields" link and scroll the table to the right to see the values.

Refer to the "Step-by-step configuration instructions" section above to add a new instance of the WorkRamp Okta application and configure the application for SCIM provisioning. Please follow the instructions under that section exactly; otherwise the import step below will not work. NOTE: If you are using SAML for login, you will also need to update your SAML settings in WorkRamp. You can do so by navigating to "Settings" and "Enterprise" and scrolling down to the "SSO Settings" section. Here is the configuration guide for SAML.

After SCIM provisioning has been enabled, go to the "Import" tab of your new WorkRamp app instance and click "Import Now". You will get a list of imported users. Click the checkbox at the top to select all of them and then click "Confirm Assignments".

At this point, all of your existing users will have been assigned to the new WorkRamp application instance. You can now proceed to set up group sync functionality if applicable. Refer to the "Group sync configuration" and "Fully-automated group sync" sections in this guide.

You can now remove/deactivate the old WorkRamp application instance.