Follow

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:

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

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

UserPro01.png

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).                                                                                                  UserPro02.png                                                                                                                                                     
  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.                                                                                                            Okta_api.png                                                                                                                                                                               
  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).

03_CopyAPIKey.jpg

 

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:

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

NOTEif 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").

JostleApp.png

 

Integration

Upon selecting the Jostle app:

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

AddIntegration.png

  1. In the app, go to Provisioning and then under Settings, click Integrations
  2. In the center of this page click the Configure API Integration button Okta_config.png                                                                                                                                                      
  3. Next, check the box next to Enable API integration
  4. 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.Okta_enable.png                                                                                                                                                    
  5. Right below those fields, click the Test API credentials button (a successful verification message should appear at the top of the screen).
  6. 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. 

OktaToJostle.png

 

Provisioning to App

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

Okta23_11.png

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)

Okta23_08b.png

 

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)

 

CreateUpdate.png

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.

 

Create-Update.png

 

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.

EnableIt.png

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

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

2 Comments

  • 0
    Avatar
    David Kuei

    The Jostle app in the Okta integration catalog shows a date of September 8, 2023, but it's not clear if this is the "updated" app or if we are still waiting for an update. I'm not sure how frequently this particular page gets updated.

  • 0
    Avatar
    Jostle Team

    Hi David,

    The message at the top of this article recommending that users not update to the most recent version of the app is referring to the September 8 version. We'll update this article as well as communicate directly with all of our Okta users when the newer version is available (which should be fairly soon).

    Vince

Please sign in to leave a comment.