Okta Integration (SCIM)

About the integration
Setting up the integration
Adding attributes to the synchronization
Troubleshooting and Frequently Asked Questions
Setting up Single Sign-On (SSO) with Okta

About the integration

Once set up, our integration with Okta allows you to automate the user management and/or to use Single Sign-On in Leapsome:

If you choose to activate user provisioning with Okta, you can use the following features:

• Pushing New Users: Creating a new user in Okta and assigning them to the Leapsome application will create a new user in Leapsome.
• Pushing User Profile Updates: Updates to a user in Okta will be pushed to Leapsome.
• Deactivating Users: Deactivating the user or disabling the user's access to Leapsome within Okta will deactivate the user in Leapsome.
• Importing New Users: Users created in Leapsome can be pulled into Okta and turned into new AppUser objects for matching against existing Okta users.
• Pushing Groups: Groups created in Okta can be pushed to Leapsome. Attributes pushed include name and group members.
• Pulling Groups: Groups created in Leapsome can be pulled into Okta for reference within Okta.

The sync frequency depends on the source system.

Which user attributes can be synchronized? 

During the setup, you can define a user attribute mapping for the integration. Like that, you can define which data from Okta should show in Leapsome. The sync allows you to update attributes like a user's email, manager, team memberships, and more, automatically based on your Okta data. 

This table gives you a first overview of the Leapsome-attributes you can populate from Okta, and contains a short explanation of what these attributes are being used for in Leapsome. Please note that only the attributes listed as 'mandatory' are required for the integration to work, while you are free to add further attributes, depending on your desired setup in Leapsome. It is best to briefly have a discussion between the person setting up the integration and the Leapsome Admin, to make sure all desired/necessary attributes are being sent to Leapsome. 

Setting up the integration

Before you get started

• Add the Leapsome App from the Okta App Catalog and make sure you have configured the General Settings for it. Confirm your changes by clicking 'Done'
  
• Generate an Access Token within Leapsome
  1. Log in as an Admin and navigate to 'Settings' > 'Integrations and imports' > 'HRIS Integrations'
  2. Select the tab 'SCIM (Azure AD, Okta, OneLogin)'
  3. Click 'Update & Synchronize'
  4. Copy the SCIM Authentication Token

Activating the integration in Okta

• Within Okta, navigate to 'Applications' and click on the Leapsome App.
• On the 'Provisioning' Tab, click on the button 'Configure API Integration'
  

• Check the 'Enable API integration' box
• Within the 'API Token' textbox, enter the token you generated in Leapome earlier
• By checking the box next to 'Import Groups', you have the option to pull Teams that are already in your Leapsome Account to your Okta account. We recommend leaving this box unchecked, as Okta should be the source of truth for your Groups.
• Click 'Test API Credentials', to check if your Token is working properly
• Once this test was successful, save your settings by clicking 'Save'
  
  

Configuring the Provisioning in Okta

1. Configure 'To App' settings

On the 'To App' tab, enable the following options, by clicking on 'Edit'

• Create Users (default username should be set to Email - you can edit this by clicking on 'default username')
• Update User Attributes
• Deactivate users

In the Leapsome attribute mappings, choose the following settings, or adjust based on the options within this table:

Please note, that in addition to this attribute mapping, you can also leverage Okta Groups to create 'Generic Teams' in Leapsome. Learn more about pushing Groups here.

2. Configure 'To Okta' settings

On the 'To Okta' tab, choose the following settings

• Schedule import: 'Never'
• Okta username format: 'Email Address'

3. Assign users to the Leapsome App

You can now assign people to the app and finish the setup. To do that, just navigate to the 'Assignments' Tab of the Leapsome App, and add People or Groups as you prefer.

For the initial user provisioning, 2 forced syncs are recommended: the first sync will create the users and the second sync will update the reporting lines.

Adding attributes to the synchronization

You can also add further attributes to the synchronization between Okta and Leapsome.

1. Add additional attributes to the 'Leapsome User Profile' in Okta

If you wish to sync additional attributes, please navigate to the 'Provisioning' > 'To App' and click 'Go to Profile Editor', followed by 'Add attribute'. Within this menu, you will now first create and define the target attributes that Okta should send information from your Directory to.

You can add a number of default Leapsome attributes and custom attributes (see below). Please note their exact external names and the external namespace (below) and choose other properties as you prefer to see them in Okta:

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

• Location:
  • external name: location
  • required format: string
• Start date
  • external name: startDate
  • required format: string, YYYY-MM-DD
• End date
  • external name: endDate
  • required format: string, YYYY-MM-DD
• Birthday
  
  • external name: birthday
  • required format: string, YYYY-MM-DD
• Level 
  
  • external name: level
  • required format: string
• Additional Managers
  • external name: additionalManagers
  • required format: string, comma-separated list of email addresses
• Any custom attribute
  • external name: Custom Attribute ID from Leapsome, e.g. 62fdf81aad7b3e32f4040f2e 

You can also send data from Okta to custom Leapsome attributes. If you want data from Okta to appear as a custom attribute in Leapsome, please first create the corresponding attribute in Leapsome by following these instructions. Please copy the ID of your custom Attribute, as you will need it for the setup. 

2. Define a mapping for these new attributes

Once you have created your attributes, please click on 'Mappings' within the 'Profile Editor', go to 'Okta User to Leapsome' and select the properties in Okta that should be mapped to your newly created attributes.

Please note that additional attributes will only be synced on the first update (not creation) run, so you'd need to enforce two syncs to make these attributes show in Leapsome.

Troubleshooting and Frequently Asked Questions

Cost center and department as 'teams' in Leapsome

Up until July 2024, Leapsome did not differentiate between different types of teams. In return, the values of attributes mapped to Leapsome's department or costCenter would appear as Generic Teams in Leapsome. 

Since July 2024, Leapsome is able to differentiate between different team types. In return, values of attributes mapped to Leapsome's department or costCenter will now appear as Department or Cost Center in Leapsome. 

The manager is not syncing

Make sure that the manager exists within Leapsome before provisioning. Leapsome will ignore any manager assignments that include managers not present in Leapsome. 

Okta sends the manager information present in the managerId field for a given user. The information in the field can be:

• an email address for the manager
• a Leapsome ID for the user
• Okta's ID for the user

Make sure this field is populated.

For the initial user provisioning, two forced syncs are recommended: the first sync will create the users and the second sync will update the reporting lines.

A forced sync is not resolving my issue. What else can I try?

In some cases, also enforcing a sync between Okta and Leapsome does not resolve previous issues (e.g. certain attributes not syncing, user (de-) activations not being handled properly).

If a "forced sync” fails, please cautiously (see warning below) try the following and retry:

• deactivate user de-provisioning in Okta
• unassign the app from all users in Okta
• re-assign the app to all users in Okta
• reactivate user de-provisioning in Okta

Attention! Please always disable the automatic user de-provisioning in Okta first. Unassigning the Okta app without this step will deactivate all users in Leapsome. Deactivating users during ongoing processes can lead to irreversible data loss.

Can I change the userName?

Leapsome depends on the uniqueness of a user’s email address. Therefore, provisioning will fail if a user’s userName is updated but their email address is not.

Updates or de-provisioning are not working for some users

This issue may occur when a user was added to Leapsome manually or prior to SCIM being enabled. Please see the 'I have added user manually to Leapsome before setting up the integration. How can I ensure that Okta can recognize them?' below.

I receive an 'Email address already in use?' error when creating a user

This error may occur when a user was added to Leapsome manually or prior to SCIM being enabled. Please see the FAQ 'I have added user manually to Leapsome before setting up the integration. How can I ensure that Okta can recognize them?'

I have added user manually to Leapsome before setting up the integration. How can I ensure that Okta can recognize them?

Users added to Leapsome manually or before SCIM was enabled for the Leapsome account may not be tracked by Okta. To make Okta aware of these users' membership in Leapsome, perform an 'Import' within Okta. Under the Leapsome app in Okta, find the 'Import' tab, and click 'Import Now'.

A list of Leapsome users and possible associations with Okta users will be populated below. Click 'Confirm Assignments' and these users will now be tracked, updated, and de-provisioned by Okta. Please make sure all of the users you would like to import from Leapsome are active as inactive users will not be imported by Okta. 

Using Okta Groups to create and Update 'Teams' in Leapsome

We suggest to create groups in Okta first and then push those groups to Leapsome via the 'Push Groups' button in Okta.

If you have groups already in Leapsome and want to associate those groups with groups in Okta, take the following steps:

1. Create a group with the same name in Okta. For example, if a 'Strategy' group exists in Leapsome, create a 'Strategy' group in Okta.
2. Add members to the group in Okta.
3. Push the group to Leapsome (only the name of the group and its members will be pushed).

If a group in Okta has the same name as an existing team in Leapsome, pushing the group from Okta to Leapsome will not create a new group. Instead, the group from Okta will overwrite the membership of the group in Leapsome.

Our organization uses plenty of organizational units (e.g. departments, teams, subteams, squads, tribes, project teams, ...) - Can all of these be synchronized with Leapsome?

This is possible, by pushing Okta groups to Leapsome to create 'Generic Teams' in Leapsome as described in the previous FAQ. The advantage of this approach is that you have no limits in terms of how many different groups you push to Leapsome. It is also possible to combine both the attribute mapping and pushing of Groups to make sure all organizational units you want to see in Leapsome can be synchronized.

In addition to that, you can assign users to Departments and Cost Centers by defining a user attribute mapping as described here.

Setting up Single Sign-On (SSO) with Okta

If you want to set-up Single Sign-On with Okta, you find a step-by-step instruction within your Okta application. This will also show your personalized values for the SSO Login URL and Base64-encoded certificate required within Leapsome. To find the set-up instructions, please navigate to the Leapsome application in Okta > Sign-On and click "View SAML setup instructions" on the right side of the page.