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:
- Log in to your Okta org as an Admin.
- Open the Admin UI
- Click on Add Applications
- Add the new instance of the Jostle app
- Configure the application including Provisioning (see the guide below)
- 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).
- Go back to your Admin Dashboard.
- Open your old Jostle App app instance (NOTE—this is the previous Jostle app you added before adding a new one in step 4).
- Go to the Provisioning tab.
- In the Settings section, click on API
- Click on Edit and uncheck Enable API Integration. Click Save.
- 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
- On the Manage User Provisioning page, scroll down to the User Provisioning API Details section.
- 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).
- Next, click the Add a new key...button
- On the following screen, go to the Automation User field and use the drop-down menu to select your newly-created automation user.
- In the Provisioning API key description field give your key a name (i.e. “Okta”) and then click the Add button.
- 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.
| Attributes | Description |
| Given Name | The given name of the User, or First Name in most Western languages (for example, Barbara given the full name Ms. Barbara J Jensen, III.). Cannot exceed 30 characters |
| Family Name | The family name of the User, or Last Name in most Western languages (for example, Jensen given the full name Ms. Barbara J Jensen, III.). Cannot exceed 40 characters |
| Nickname | The casual way to address the user in real life, e.g., 'Bob' or 'Bobby' instead of 'Robert'. This attribute SHOULD NOT be used to represent a user’s username (e.g., bjensen or mpepperidge) |
| Personal Pronouns | The set of pronouns a user wishes to be identified by. |
| Birth Date | The user's date of birth, format: MM/dd/yyyy |
| Join Date | The user's join/associated date with the organization, format: MM/dd/yyyy |
| Employee Number | Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization. |
| Custom Filter Category | A list of predefined custom filter category names in the Jostle platform |
| Job Title | The user's job title. This field only takes effect if Teams is not enabled in Jostle. |
| Job Category | The user's job category. |
| Custom Badge | The user's custom badge value. The Badge program should already be configured prior to entering data here, entries not matching previously set values will be ignored. |
| Primary Email | Email shown based on the preference of the user |
| Primary Email Type | Email type shown based on the preference of the user |
| Work Email | Work email of the user, which is also used to create Jostle Username. |
| Personal Email | Personal email ID for the user |
| Alternate Email 1 – Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Alternate Email 1 - Value | A value indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Alternate Email 2 – Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Alternate Email 2 - Value | A value indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Primary Phone | Phone number shown based on the preference of the user |
| Primary Phone Type | Phone type shown based on the preference of the user |
| Phone Office | User's office phone number |
| Phone Personal | User's personal phone number |
| Mobile Office | User's work mobile number |
| Mobile Personal | User's personal mobile number |
| Custom Label 1 - Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Custom Label 1 - Value | A value indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Custom Label 2 - Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Custom Label 2 - Value | A value indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Custom Label 3 - Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Custom Label 3 - Value | A value indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Locations | A list of locations by name or id, which are predefined in the Jostle platform |
| Address 1 - Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Address 1 - Street Address | The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This attribute MAY contain newlines. |
| Address 1 - City | The city or locality component. |
| Address 1 - Region | The state or region component. |
| Address 1 - Country | The country name component. |
| Address 1 - Postal | The zip code or postal code component. |
| Address 2 - Label | A label indicating the attribute's function; e.g., 'address1', 'address2', 'label1', 'label2', 'label3', 'altemail1', 'altemail2', 'customuserfield', 'customprofilefield' |
| Address 2 - Street Address | The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This attribute MAY contain newlines. |
| Address 2 - City | The city or locality component. |
| Address 2 - Region | The state or region component. |
| Address 2 - Country | The country name component. |
| Address 2 - Postal | The zip code or postal code component. |
| Custom Profile Category | This is a field found on Profiles under Info > Other that has its label set org wide and its values constrained to a list of categories. |
| Custom Label - Custom Profile Field Label | This is a field found on Profiles under Info > Other that can have its label set per user via text. It appears right below the Custom Profile Category. |
| Custom Label - Custom Profile Field Value | This is a free-form value that corresponds to the Custom Profile Field Label found on Profiles under Info > Other. Set per user. |
| Custom Label - Custom User Field Label | This is a free-form label for another optional field of data that can be added to Profiles under Info > Other, right below the Custom Profile Category. Set per user. |
| Custom Label - Custom User Field Value | This is a free-form value that corresponds to the Custom User Field Label found on Profiles under Info > Other. Set per user. |
| Visibility Work Email | Set the value for visibility for work email to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Team's view is disabled. |
| Visibility Personal Email | Set the value for visibility for personal email to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Team's view is disabled. |
| Visibility Alternate 1 Email | Set the value for visibility for alternate 1 email toEVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Teams view is disabled. |
| Visibility Alternate 2 Email | Set the value for visibility for alternate 2 email to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Teams view is disabled. |
| Visibility Home Phone | Set the value for visibility for home phone to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Teams view is disabled. |
| Visibility Personal Mobile Phone | Set the value for visibility for personal mobile phone to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Teams view is disabled. |
| Visibility Address 1 | Set the value for visibility for address 1 to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Teams view is disabled. |
| Visibility Address 2 | Set the value for visibility for address 2 to EVERYONE, DIRECT CONNECTIONS or NOBODY. Direct Connections is not available if Teams view is disabled. |
| Login Type | Specifies method (PASSWORD, GOOGLE, SSO) for invited users to log in if they are set to be automatically invited. If no value is entered, invite will be sent via org's default method. No invites will be sent if users are set to be manually invited. |
| User Type | Indicates a certain level of access and permissions for a user in the platform. Can be set to REGULAR, RESTRICTED, SEMI-RESTRICTED, or SHARED. Defaults to REGULAR if no value is entered, including when a suspended user has been made active again. The SUSPENDED value is auto-populated and should never be manually entered. |
Based on the above list, choose the attributes you wish to keep and add them to the Okta User Profile as follows:
- Go to the column on the left side of the Admin Console and select Directory > Profile Editor
- Select Okta User (default) application
- Add the selected attributes and use the below table for reference.
| Attribute Type | Data Type | Variable Name | Enums |
| Base | String | userName | |
| Base | String | givenName | |
| Base | String | familyName | |
| Base | String | nickName | |
| Custom | String | personalPronouns | |
| Custom | String | birthDate | |
| Custom | String | joinDate | |
| Custom | String | employeeNumber | |
| Custom | String Array | customFilterCategory | |
| Custom | String | jobTitle | |
| Custom | String | jobCategory | |
| Custom | String | customBadge | |
| Custom | String | work, personal, alternate1, alternate2 | |
| Custom | String | emailType | |
| Custom | String | workEmail | |
| Custom | String | personalEmail | |
| Custom | String | customLabels_altemail1 | |
| Custom | String | alternateEmail1 | |
| Custom | String | customLabels_altemail2 | |
| Custom | String | alternateEmail2 | |
| Custom | String | primary_phone | workofficephone, homephone, workmobilephone, personalmobilephone |
| Custom | String | phoneType | |
| Custom | String | phoneNumbers_workOffice_number | |
| Custom | String | phoneNumbers_homePhone_number | |
| Custom | String | phoneNumbers_workMobile_number | |
| Custom | String | phoneNumbers_personalMobilePhone_number | |
| Custom | String | customLabels_1_label | |
| Custom | String | customLabels_1_value | |
| Custom | String | customLabels_2_label | |
| Custom | String | customLabels_2_value | |
| Custom | String | customLabels_3_label | |
| Custom | String | customLabels_3_value | |
| Custom | String Array | locations | |
| Custom | String | customLabels_address1_label | |
| Custom | String | address_1_street | |
| Custom | String | address_1_city | |
| Custom | String | address_1_region | |
| Custom | String | address_1_country | |
| Custom | String | address_1_postal | |
| Custom | String | customLabels_address2_label | |
| Custom | String | address_2_street | |
| Custom | String | address_2_city | |
| Custom | String | address_2_region | |
| Custom | String | address_2_country | |
| Custom | String | address_2_postal | |
| Custom | String | customProfile | |
| Custom | String | customLabels_customprofilefield | |
| Custom | String | customLabels_customprofilefield_value | |
| Custom | String | customLabels_customuserfield | |
| Custom | String | customLabels_customuserfield_value | |
| Custom | String | visibility_personalEmail | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | visibility_alternate1Email | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | visibility_alternate2Email | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | visibility_personalMobilePhone | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | visibility_homePhone | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | visibility_address1 | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | visibility_address2 | EVERYONE, DIRECT_CONNECTIONS, NOBODY |
| Custom | String | loginType | GOOGLE, PASSWORD, SSO |
| Custom | String | userType | REGULAR, SEMI-RESTRICTED, RESTRICTED, SHARED |
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:
- Click on the Add Integration button on the top right of the application profile.
- In the app, go to Provisioning and then under Settings, click Integrations
- In the center of this page click the Configure API Integration button
- Next, check the box next to Enable API integration
- 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.
- Right below those fields, click the Test API credentials button (a successful verification message should appear at the top of the screen).
- 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).
2 Comments