Okta (from Leapsome to Okta via Okta app)

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.

Leapsome connects through an API Services app that you create in your own Okta org. Leapsome generates a key for the connection. You add its public half to the app in Okta, and the private half never leaves Leapsome. There is no client secret to copy or store.

Contents

• Prerequisites
• Supported features
• Configuration steps
• Troubleshooting
• Replace the signing key
• Disconnect the integration
• Support

Prerequisites

In Okta

• A super admin. Only a super admin can grant API scopes and admin roles to an app.
• 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 to 30 minutes. Most of the work happens in the Okta Admin Console. Keep Leapsome open in a second tab, because you'll switch between the two.

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 4), 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 10.
• 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 the app needs

Configuration steps

The steps below follow the same order as the setup steps shown in Leapsome.

Step 1: Add the Custom Identity Source app in Okta

1. In the Okta Admin Console, go to Applications > Applications and select Browse App Catalog.
2. Search for Custom Identity Source and select Add Integration.
3. Enter an Application label your team will recognize, for example "Leapsome", and select Done.
4. Stay on the app page and copy the app 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 9.

[Screenshot: Add Custom Identity Source with the application label]

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

Step 2: Enable the API integration

Until this is on, the app has no To Okta settings.

1. On the app, open the Provisioning tab.
2. Select Configure API Integration.
3. Select Enable API integration and select Save.

[Screenshot: Provisioning tab with Enable API integration selected]

Step 3: Allow the app to source Okta users

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

1. On the Provisioning tab, select To Okta.
2. Under Profile & Lifecycle Sourcing, select Edit.
3. Select Allow Custom Identity Source to source Okta users and select Save.

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

Step 4: Set the import matching rules

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.

1. On Provisioning > To Okta, under User Creation & Matching, select Edit.
2. Set:
   • Imported user is an exact match to Okta user if: Email matches
   • Allow partial matches: off
   • Auto-confirm exact matches: on
   • Auto-confirm partial matches: off
   • Auto-confirm new users: on
   • Auto-activate new users: on
3. Select Save.

[Screenshot: User Creation & Matching settings]

Step 5: Generate a key in Leapsome

Do this before you set up the API Services app. Okta doesn't save key-based authentication until a key has been added.

1. In Leapsome, go to Settings > Integrations > HRIS, open the Outbound Provisioning tab, and select Okta.
2. In the setup steps, select Generate key.
3. Leapsome shows a Public key (JWK). Select Copy.

You can come back to this screen at any time. Leapsome keeps showing the same key until you disconnect the integration, so it's safe to close the window and copy it again later.

[Screenshot: Leapsome Okta setup with the generated public key and Copy button]

Step 6: Create the API Services app in Okta

1. In the Okta Admin Console, go to Applications > Applications and select Create App Integration.
2. Select API Services and select Next.
3. Enter a name, for example "Leapsome provisioning", select Use Okta-generated client ID, and select Save.
4. On the General tab, under Client Credentials, select Edit and set Client authentication to Public key / Private key.
5. Under Public keys, keep Save keys in Okta, select Add key, paste the key you copied in step 5, and save it.
6. Select Save under Client Credentials.
7. Under General Settings on the same tab, select Edit, clear Require Demonstrating Proof of Possession (DPoP) header in token requests, and select Save.
8. Copy the Client ID shown under Client Credentials. You'll enter it in Leapsome in step 9.

[Screenshot: Client Credentials set to Public key / Private key, with the Leapsome key added]

Note: If you select Public key / Private key before adding the key, Okta shows "Add an active key or URL in the Public Keys section" and won't save. Add the key first, then save. Okta also turns on DPoP for new API Services apps by default. If you leave it on, the connection fails with a message about DPoP.

Step 7: Grant the API scopes

1. On the API Services app, open the Okta API Scopes tab.
2. Select Grant next to each of these scopes:
   • okta.identitySources.manage
   • okta.schemas.manage
   • okta.profileMappings.manage
   • okta.apps.manage

Leapsome lists the same scopes in its setup steps, so you can check them side by side.

[Screenshot: Okta API Scopes tab with the four scopes granted]

Step 8: Assign an admin role

Okta only lets an API Services app use these scopes if the app also has an admin role.

1. On the API Services app, open the Admin roles tab.
2. Select Edit assignments.
3. Under Role, select Super Administrator, and save.

[Screenshot: Admin roles tab with Super Administrator assigned]

Step 9: Connect Okta in Leapsome

1. Back in Leapsome, fill in these fields:
   • Okta org URL: your Okta base URL, for example https://acme.okta.com. Use the URL without -admin. If your Admin Console address is https://acme-admin.okta.com, enter https://acme.okta.com. Custom domains work. The URL must start with https://.
   • Client ID: the client ID of the API Services app from step 6.
   • Identity source ID: the 0oa... value from step 1.
2. Select Connect Okta.

[Screenshot: Leapsome Okta connection form]

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

If a step says the app lacks permission, check that all four scopes are granted (step 7) and that the app has an admin role (step 8), then select Sync now.

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

Step 10: 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 4 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:

1. In Okta, go to Directory > Profile Editor and open the User (default) profile. This is the Okta user profile, not the identity source app.
2. Select Add Attribute and create it with Data type: string.
3. 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

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 11: Run the first sync

1. Select Sync now. Leapsome saves your settings, runs the setup checks from step 9 again, and sends every eligible employee to Okta.
2. To check the result in Okta, open the identity source app and select Monitor Imports, 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.

Troubleshooting

Replace the signing key

Leapsome keeps one key per account. To replace it, for example if you think it was exposed, disconnect and connect again:

1. Before you start, note your attribute mapping and the two settings under Activation and deactivation. Disconnecting removes them.
2. In Leapsome, select Revoke authorization. This deletes the key.
3. In Okta, open the API Services app and remove the old key under Public keys.
4. In Leapsome, select Generate key, add the new key to the app in Okta, and connect again (steps 5, 6 and 9).
5. Set up your attribute mapping again and turn on Automatically create employees in Okta, then select Sync now. After a reconnect, Leapsome only sends employees to Okta when this setting is on. Okta links them to their existing users through the matching rules from step 4.

Disconnect the integration

In the Okta settings in Leapsome, select Revoke authorization. You can do this at any time, even while a sync is running. Syncing stops right away. A batch that was already being sent to Okta finishes, and nothing new starts.

Disconnecting deletes the connection details, the key, your attribute mapping and your sync settings. Employees already imported stay in Okta, and nothing is deleted there.

To also remove Leapsome's access on the Okta side, deactivate or delete the API Services app in Okta.

You can reconnect at any time by following the configuration steps again. If a batch was still running when you disconnected, Leapsome waits for it to finish before it accepts the new connection.