Skip to main content

Articles in this section

Configuring SCIM Provisioning with Okta

  • Last updated:

This article provides the steps required to configure SCIM provisioning with Okta for WorkRamp and includes the following sections:

  • Prerequisites

  • Supported features

  • Step-by-step configuration instructions

  • Group sync configuration

  • Manager sync configuration

  • Custom user attributes configuration

  • Migration to newer version

  • Gotchas & known issues

Prerequisites

The following prerequisites are required before you can configure provisioning:

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

  2. Follow the steps here to generate your API token.

Supported features

  • Create Users: New users created in Okta that have been assigned the WorkRamp application will also be created in WorkRamp

  • Update User Attributes: Updates made to a user's profile in Okta will be reflected in WorkRamp

  • Deactivate Users: Removing a user's access to the WorkRamp application in Okta can deactivate the user in WorkRamp (but not permanently delete them)

  • Reactivate Users: Giving a user access to the WorkRamp application (when you had previously removed their access) will activate the user in WorkRamp

  • Import Users: Users can be imported from WorkRamp to Okta

  • Import Groups: Groups can be imported from WorkRamp to Okta

  • Group Sync: Groups and users within groups on Okta can be kept in sync with WorkRamp

  • Manager Sync: A user's manager in Okta can be kept in sync with WorkRamp

  • Custom User Attributes: Arbitrary attributes can be set in a user's profile in WorkRamp based on values in Okta

Step-by-step configuration instructions

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

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

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

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

  1. Click the "Configure API Integration" button.

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

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

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

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

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

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

  1. 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.)

  2. 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:

    1. From the "Provisioning" tab and "To App" subtab, temporarily uncheck the "Deactivate Users" setting (so it is not enabled).

    2. From the "Assignments" tab, unassign all users from the WorkRamp Okta application. Note that since we disabled the "Deactivate Users" setting, user accounts will not be deactivated in WorkRamp. However, the WorkRamp application tile will no longer be visible in users' Okta dashboards temporarily. If you have a large number of users, please wait about 15 min for Okta to process everything.

    3. Now from the "Assignments" tab assign all the users back. This will reset the mapping on Okta's end and these users will now get all SCIM updates.

    4. Undo the change we made in step A above (enable the "Deactivate Users" setting).

Group sync configuration

We will be configuring Okta so that a group created in Okta will also be created in WorkRamp. In addition, we will configure Okta so that when a user is added/removed from a group in Okta, the user will be added/removed from the same group in WorkRamp. Please follow the instructions below.

  1. 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".

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

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

    1. Matching group exists:

  1. Matching group does not exist:

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

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

Fully-automated group sync

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

  2. 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".

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

Manager sync configuration

We will be configuring Okta so that when a user is assigned the WorkRamp application in Okta, their manager will be reflected in WorkRamp when that user is created through SCIM. This requires that the user's manager attribute is set correctly in Okta. You can configure this attribute to be set automatically if you have Okta integrated with your HRIS system (out of scope for this document) or you can manually modify their profile in Okta.

  1. 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".

  1. 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).

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

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

    1. Data type: string

    2. Display name: Manager Name

    3. Variable name: managerName

    4. External name: managerName

    5. External namespace: urn:ietf:params:scim:schemas:core:2.0:User
      Please note that the required format for the Manager Name is First Name Last Name.

      If you would like to set up the Manager value to sync over using the Manager's email address, please use the following values:
      -Data type: string

      -Display name: Manager

      -Variable name: manager

      -External name: manager

      -External namespace: urn:ietf:params:scim:schemas:core:2.0:User

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

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

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

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

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

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

Custom user attributes configuration

We will be configuring Okta so that a non-standard attribute from Okta can be synced to a user's profile in WorkRamp.

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

  2. 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".

  1. Click the "Add Attribute" button.

  1. Enter the following values in the popup modal:

    1. Data type: string

    2. Display name: Name of the custom attribute. For example: "Department ID"

    3. Variable name: This should be the same as the "API Name" in WorkRamp (from step 1 above). For example: "department_id"

    4. External name: This should be the same as the variable name.

    5. External namespace: urn:ietf:params:scim:schemas:core:2.0:User

Click the "Save" button once you have entered these values.

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

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

  1. 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".

Note: Variable name: This should be the same as the "API Name" in WorkRamp (from step 1 above). For example: "department_id" *make sure additional API names are all lowercase

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

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

Migration to newer version

NOTE: You only need to follow these instructions if specifically instructed by WorkRamp support.

WorkRamp has been updated to provide a better overall experience to Okta customers. Here is a summary of the updated functionality (these are all documented in the section above):

  • Setting a user's manager

  • Setting custom attributes on a user

  • Configuring provisioning for a WorkRamp instance hosted in a region other than the US

To take advantage of these updates, you have to add a new instance of WorkRamp in your Okta organization. If you already have an existing instance of WorkRamp, follow the steps below to migrate from the old instance to a newly updated instance of WorkRamp:

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

  2. 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".

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

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

User Deactivation

  • When deleting a user in Okta or removing their access from the WorkRamp application, the user will be marked as deactivated in the WorkRamp application. However, an Admin will still be able to manually reactivate the user's account from within WorkRamp.

In this article