User Provisioning: Okta Integration

 

Currently Jostle's User Provisioning API can only be used for integration with Okta or Azure AD. For more information about the User Provisioning API and SCIM standard, please see this article. 

 

About Jostle/Okta integration

Configuration

• Requires a two-part setup: Jostle, then Okta
• Once configured, user provisioning is one-way: Okta to Jostle

Supported provisions 

• Push New Users
  • New users created in Okta will be created in Jostle.
• Push Profile Updates 
  • Updates made to a user’s profile in Okta will be pushed to Jostle.
• Push User Deactivation
  • Deactivating a user in Okta will deactivate them in Jostle.
• Push User Reactivation
  • Reactivating a user in Okta will reactivate them in Jostle.

 

Application Update (Summer 2023)

New attributes for Okta-Jostle user provisioning have recently been added and will be automatically available for all newly-created Okta-Jostle app instances. 

If you already have an existing instance of the Jostle app, follow the steps below to migrate from that old instance to a newly updated one:

NOTE—(September 2023) it is NOT recommended that you attempt migration at this time, as there have been reports of data discrepancy issues when migrating to the current version of the app. A new version of the app will be available shortly, and we will remove this advisement once it has been released and we have confirmed that this issue is no longer a concern.

1. Log in to your Okta org as an Admin.
2. Open the Admin UI
3. Click on Add Applications
4. Add the new instance of the Jostle app
5. Configure the application including Provisioning (see the guide below)
6. After SCIM Provisioning has been enabled, go to the Assignments tab of your new Jostle app instance, click Assign and start assigning the same users/groups that are assigned to your old Jostle app instance (NOTE—make sure you assign all the users to your new Jostle app instance to avoid any accidental de-provisioning/loss of access for your users).
7. Go back to your Admin Dashboard.
8. Open your old Jostle App app instance (NOTE—this is the previous Jostle app you added before adding a new one in step 4).
9. Go to the Provisioning tab.
10. In the Settings section, click on API
11. Click on Edit and uncheck Enable API Integration. Click Save.
12. You can now deactivate or delete your old Jostle app instance and continue using the new Jostle app you added.

NOTES

If you were using SAML as the sign-on mode for your old Jostle app instance, you will need to set up SAML on your new Jostle app instance in Okta (recommended) or maintain the old Jostle app instance to ensure that the SAML functionality continues to work.

If you were using your old Jostle app as a profile master for certain Okta attributes, you would need to set your new Jostle app as the profile master for the same attributes.

 

Configuration - Setup Part 1 (Jostle)

Automation Account

Before you begin, you’ll need to create an Automation user in your Jostle platform. This will be the account you’ll use to configure with Okta. Automation users can be created in Admin Settings > User accounts and data > Manage Automation users.

For more details on Automation users and how to create one, see this article.

Once created, the Automation user account must be activated (i.e. logged in to your platform at least once) before it can be used to configure Okta.

 

Manage User Provisioning

All Jostle account subscriptions include SSO/user provisioning features. If they are not appearing on your account, you can contact your Customer Success Manager and they can assist you in getting them added.

The next step is to obtain the API URL and API key from Jostle, which you can do in Admin Settings > User Data To/From Other Systems > Manage User Provisioning (if you do not see "Manage user provisioning" here, contact Support to have this page enabled in your Admin Settings).

NOTE—this page also includes a User Account Settings section where you can automatically invite and/or disable/suspend users:

To obtain the API URL and API key

1. On the Manage User Provisioning page, scroll down to the User Provisioning API Details section.
2.  Locate the Your Base URL field and click the Copy button to its right (and save the URL somewhere you can easily access it later).                                                                                                                                                                                                                                                       
3. Next, click the Add a new key...button
4. On the following screen, go to the Automation User field and use the drop-down menu to select your newly-created automation user.                                                                                                                                                                                                                                                                                           
5. In the Provisioning API key description field give your key a name (i.e. “Okta”) and then click the Add button.
6. Once your key is generated, make sure to copy it right away and save it where you saved your URL (since this will be the only time your key will appear).

 

Next, you’ll set up the mapping and then use the API URL and API key to configure the integration in Okta.

 

Configuration - Setup Part 2 (Okta)

NOTE—the Okta integration can only be done by the Okta Admins.

 

Selecting Attributes

Supported Attributes - Below are the fields that are supported for user provisioning, along with a brief description of each.

 

Based on the above list, choose the attributes you wish to keep and add them to the Okta User Profile as follows:

1. Go to the column on the left side of the Admin Console and select Directory >  Profile Editor
2. Select Okta User (default) application
3. Add the selected attributes and use the below table for reference.

 

Assigning users to the Jostle app

NOTE—if you add your users to the app before enabling integration and turning on user provisioning, you will need to reassign them afterwards in order for them to be recognized and synced.

If you haven't done so already, sign into Okta and download the Jostle app (Applications > Browse App Catalog > Search "Jostle").

 

Integration

Upon selecting the Jostle app:

1. Click on the Add Integration button on the top right of the application profile.

2. In the app, go to Provisioning and then under Settings, click Integrations
3. In the center of this page click the Configure API Integration button                                                                                                                                                       
4. Next, check the box next to Enable API integration
5. Then go down to the Base URL field and enter the URL you copied from Jostle. Below that, in the API Token field, enter the API key you generated in Jostle.                                                                                                                                                    
6. Right below those fields, click the Test API credentials button (a successful verification message should appear at the top of the screen).
7. Click Save

Settings

Once the integration is successfully completed, click on Provisioning from the row at the top. If you check the Settings column on the left, you should now be in the To App section. 

 

Provisioning to App

Across from the Provisioning to App heading, click the Edit button 

Then select which of the following provisioning actions you want to enable:

• Create User - Creates or links a user in Jostle when assigning the app to a user in Okta.
• Update User Attributes -  Okta updates a user's attributes in Jostle when the app is assigned. Future attribute changes made to the Okta user profile will automatically overwrite the corresponding attribute value in Jostle (only recommended if you've read and understood the “NOTE” about pushing updates, below) 
• Deactivate Users - Deactivates a user's Jostle account when it is unassigned in Okta or their Okta account is deactivated. Accounts can be reactivated if the app is reassigned to a user in Okta.

After saving your selections, scroll down to the next section, Jostle New Attributes Mapping.

 

Mapping 

From the Jostle New Attributes Mapping list you can:

• Delete any unnecessary attributes (click the x to the far right of the attribute)
• Indicate which actions you want to apply each attribute to (click the pencil/edit icon)

 

NOTE—if you enabled both "Create Users" and "Update User Attributes" in the previous section, you will be able to edit each attribute and indicate whether you want to map it just when creating new users or when creating and updating users (see the NOTE about updating below). 

 

Once you make and save a selection it will be immediately reflected on the Mapping Attributes list. Continue through this list of attributes, making any necessary deletions or edits, until you are satisfied with your mapping setup.

 

 

NOTE—Important message about pushing user updates: 

Due to Okta’s mapping configuration, we recommend not enabling the Update User Attributes option in Okta's Provisioning to App settings once you have completed your setup (see image below) and only use Okta > Jostle User Provisioning to create or deactivate users.

This is because enabling the Update User Attributes option will result in the removal of any data that appears in a user's Jostle Profile that doesn't map to any existing data in their Okta Profile. For example:

• Say a user has entered "Joey" as their Nickname on their Jostle Profile. Since that data doesn’t exist in their Okta account, enabling Update User Attributes in Okta will result in the "blank" Nickname data from Okta overriding the entered data Nickname data in Jostle - removing “Joey” from their Jostle Profile.

However, if you do wish to push user updates, but want to avoid the chance of accidentally removing any previously-entered data,  SFTP is always an option (and it offers even more attributes for importing and updating your users' account information).