Okta (from Leapsome to Okta)

Please note: The OIN Okta app is currently under review and will be published soon. The below is a preview.

Leapsome Okta provisioning configuration guide

This guide explains how to set up Leapsome as an HR source for Okta. Once it's set up, Leapsome creates and updates users in Okta and can optionally deactivate them, based on employee data in Leapsome.

Contents

Prerequisites
Supported features
Configuration steps
SP-initiated SSO
Troubleshooting
Rotate the client secret
Disconnect the integration
Support

Prerequisites

In Okta

A super admin, or an app admin with equivalent rights.
The Identity Source Apps feature turned on for your Okta org. It is off by default. Ask your Okta account team to turn it on.

In Leapsome

A user with the Manage integrations permission.

Time

About 20 minutes. Most of the work happens in the Okta Admin Console.

Supported features

Leapsome uses Okta's Identity Sources API, so Okta treats Leapsome as the source of truth for employee profiles.

Create users: Leapsome sends active employees to Okta. Okta links each one to an existing user or creates a new user, depending on your import matching rules.
Update user attributes: changes to mapped employee attributes in Leapsome reach Okta automatically, usually within a few minutes.
Deactivate users (optional): when you deactivate an employee in Leapsome, they are removed from the identity source. Okta then applies the lifecycle policy you set for users removed from a source.
Custom attribute mapping: you can map Leapsome's standard and custom attributes to Okta's standard and custom user attributes.
Manager sync: the primary manager can be written to Okta's managerId, so Okta Identity Governance can use it, for example for approvals.

Restrictions and limitations

The sync runs one way, from Leapsome to Okta. Changes made in Okta do not reach Leapsome, and attributes Leapsome writes become read-only in Okta.
Leapsome does not manage Okta groups. Use Okta group rules based on the attributes Leapsome writes, such as department or division.
You have to set the import matching rules by hand in Okta (step 5), because Okta does not offer an API for them on Custom Identity Source apps.
Okta identity source profiles only hold text, so every value is converted to text. See "How values are written" in step 6.
Leapsome never deletes users in Okta.
You can't map compensation, payroll, equity, emergency contacts, relocation or diversity fields.
This integration only handles provisioning. Single sign-on to Leapsome is a separate integration and is not covered in this guide.

Okta API scopes Leapsome requests

Scope	Used to
`okta.identitySources.manage`	Send employees to the identity source and remove them from it
`okta.schemas.manage`	Add the attributes you map to the identity source app's user profile
`okta.profileMappings.manage`	Map those attributes onto the Okta user profile
`okta.apps.manage`	Check the identity source app and its provisioning settings

Configuration steps

Step 1: Create the Custom Identity Source app in Okta

In the Okta Admin Console, go to Applications > Applications.
Select Browse App Catalog.
Search for Custom Identity Source and select Add Integration.
Give it a name your team will recognize, for example "Leapsome", and save.
Stay on the app page and copy the app instance ID from your browser's address bar. It starts with 0oa and looks like 0oa1b2c3d4EXAMPLE5. This is your identity source ID, which you'll enter in Leapsome in step 4.

[Screenshot: app page with the 0oa ID in the address bar highlighted]

Step 2: Allow the app to source Okta users

Until profile sourcing is on, Okta rejects every provisioning request for this app.

On the app you just created, open the Provisioning tab.
Select To Okta.
Under Profile & Lifecycle Sourcing, select Edit.
Select Allow app to source Okta users and save.

[Screenshot: Profile & Lifecycle Sourcing with the option selected]

Step 3: Install Leapsome from the Okta Integration Network

Go to Applications > API Service Integrations.
Select Add Integration.
Choose Leapsome, then select Add.
Review the requested scopes and select Install & Authorize.
Okta shows a client ID and a client secret. Copy both right away. Okta shows the secret only once and you can't retrieve it later. If you lose it, generate a new secret and follow "Rotate the client secret" below.

[Screenshot: client ID and client secret dialog]

Note: you must install Leapsome from the Okta Integration Network. A service app you create yourself under Create App Integration > API Services won't work, because Okta only accepts private key authentication for those apps.

Step 4: Connect Okta in Leapsome

In Leapsome, go to Settings > Integrations > HRIS, open the Outbound Provisioning tab, and select Okta.
Fill in these fields:
- Okta org URL: your Okta base URL, for example https://acme.okta.com. Custom domains work. It must start with https://.
- Client ID: from step 3.
- Client secret: from step 3. Leapsome stores it encrypted and only uses it to authenticate with Okta.
- Identity source ID: the 0oa... value from step 1.
Select Connect Okta.

[Screenshot: Leapsome Okta connection form]

Leapsome checks your credentials and the identity source app, then sets up the app for you. The Okta setup panel shows the result of each step:

Setup step	What Leapsome does	If the panel shows "Finish in Okta" or "Failed"
Identity source app verified	Confirms the app exists and is active	Activate the app in Okta, then select Sync now
Profile attributes declared on the identity source	Adds every attribute you map to the app's user profile, so Okta accepts the values	Add the attributes under Directory > Profile Editor on the identity source app
Attributes mapped to the Okta user profile	Maps each attribute onto the matching Okta user attribute	Map them under the app's Profile Editor > Mappings
Import matching rules configured	Tries to set the "To Okta" matching rules	Set them yourself in step 5. This step always shows Finish in Okta, which is expected.

Leapsome runs these checks again every time you select Sync now and whenever you save a mapping that adds an Okta attribute.

Step 5: Set the import matching rules in Okta

Okta doesn't let Leapsome change these settings on Custom Identity Source apps, so you always set them by hand. The rules tell Okta what to do with the employees Leapsome sends. Without them, every imported user waits in Okta until someone confirms them by hand.

In Okta, open the identity source app.
Go to Provisioning > To Okta.
Under User Creation & Matching, select Edit and set:
- Match against: Email
- Auto-confirm exact matches: on
- Auto-confirm partial matches: off
- Auto-confirm new users: on
- Auto-activate new users: on
Save.

[Screenshot: User Creation & Matching settings]

Step 6: Choose what to sync

Activation and deactivation

Both settings are off by default.

Automatically create employees in Okta: when on, Leapsome sends every active employee to Okta, and Okta creates users for anyone its matching rules can't link to an existing account. When off, Leapsome only updates employees it has already sent to Okta.
Propagate deactivation to Okta: when on, an employee you deactivate in Leapsome is removed from the identity source, and Okta applies the lifecycle policy you set for users removed from a source, typically suspend or deactivate. Leapsome never deletes Okta users.

Best practices

Finish step 5 before you turn on Automatically create employees in Okta. Otherwise Okta holds every imported user for manual confirmation.
Before you turn on Propagate deactivation to Okta, check that the Okta lifecycle policy for users removed from a source does what you expect, and confirm the first import looks right.

Attribute mapping

The table under Map attributes controls which Leapsome attribute is written to which Okta attribute. First name, last name and primary email are mapped for you and can't be removed. Use New attribute mapping to add more rows.

Leapsome attributes: the standard attributes (names, contact details, address, employment data, start and end dates, level, legal entity, work location, and org structure assignments such as departments, cost centers, business units and divisions), plus any custom attribute in your account.
Okta attributes: Leapsome reads this list from your Okta org, so your custom Okta attributes appear next to the standard ones.

[Screenshot: Map attributes table]

Add a custom Okta attribute

To send a Leapsome attribute to an Okta attribute that doesn't exist yet:

In Okta, go to Directory > Profile Editor and open the User (default) profile. This is the Okta user profile, not the identity source app.
Select Add Attribute and create it with Data type: string.
In Leapsome, close and reopen the Okta settings. The new attribute appears under Okta custom attributes.

An Okta attribute won't appear in the list if:

it isn't a string,
Okta marks it read-only,
its variable name doesn't start with a letter, or is longer than 64 characters, or
it's one of login, userName or id. Leapsome uses the work email as the identifier Okta matches on.

How values are written

Leapsome value	Written to Okta as
Text, URL, email, phone, currency, single select	The value
Number, formula, monetary	The number as text
Yes/no	`true` or `false`
Date	`YYYY-MM-DD` (UTC)
Work location, legal entity, level	The name
Multi select, or several org assignments	The values separated by commas
Person or People custom attributes	Can't be mapped

If a mapped Leapsome attribute no longer exists, Leapsome writes an empty value instead of guessing, which clears the attribute in Okta.

Managers

Map Primary manager to Manager (login) if you want Okta to resolve the manager to a real user, for example for Okta Identity Governance approvals. This writes the manager's work email to Okta's managerId. Mapping it to Manager (display name) writes their name as plain text instead.
When you rename a manager in Leapsome, their direct reports are updated in Okta on the next sync.
Map Additional managers to a custom Okta attribute. They are written as a comma-separated list of logins. Don't map them to managerId, because it holds only one user.

Step 7: Run the first sync

Select Sync now. Leapsome saves your settings, runs the setup checks from step 4 again, and sends every eligible employee to Okta.
To check the result in Okta, open the identity source app and look at Import Monitoring, or open a user under Directory > People and look at their profile.

From then on, changes reach Okta automatically. When you edit an employee in Leapsome, they're queued for the next batch, usually within a few minutes. If a batch fails, Leapsome retries pending changes on its own.

SP-initiated SSO

This integration only handles provisioning and doesn't support signing in. To sign in to Leapsome with Okta, set up single sign-on separately.

Troubleshooting

Message in Leapsome	What to do
Okta rejected the provided credentials.	Check the org URL, client ID and client secret. If the secret was rotated in Okta, enter the new one and connect again.
The Leapsome integration installed in Okta does not grant all required permissions.	Reinstall Leapsome under Applications > API Service Integrations and accept every requested scope.
The identity source could not be verified.	Check that the identity source ID is the `0oa...` app instance ID and that the app is active.
Profile sourcing is turned off for this identity source app.	Repeat step 2.
The identity source app is deactivated in Okta.	Activate the app in Okta and select Sync now.
One of the selected Okta attributes does not exist in your Okta org.	Someone removed it in Okta. Reopen the settings to refresh the list and pick another attribute.
One of the mapped Leapsome attributes no longer exists or cannot be sent to Okta.	A custom attribute was deleted in Leapsome. Pick a different one.
Could not read the attribute list from your Okta org.	This is usually temporary. Reopen the settings in a moment. Until then, only Okta's standard attributes are listed.
A sync is already running. / A sync is currently running.	Wait for it to finish, then try again. The panel shows progress.
Issues from the last sync	Expand the row above the settings. Each entry names the employee it concerns. "Missing required fields" means the employee has no first name, last name or work email in Leapsome. If Okta rejected an employee's profile, Leapsome retries it once that employee's data changes.
Imported users wait in Okta for confirmation	Check the import matching rules from step 5.

Rotate the client secret

In Okta, open Applications > API Service Integrations > Leapsome and generate a new secret.
In Leapsome, open the Okta settings, enter the new secret, and connect again. Your attribute mapping and lifecycle settings are kept.

Disconnect the integration

In the Okta settings in Leapsome, select Revoke authorization. This stops all syncing right away and deletes the stored credentials. Employees already imported stay in Okta, and nothing is deleted there. You can reconnect at any time.

To also remove Leapsome's access on the Okta side, remove Leapsome under Applications > API Service Integrations.

Support

For help with this integration, contact Leapsome Support:

Help center: [help center URL]
Email: [support email]
Phone: [support phone number, if offered]

Articles in this section