Webhooks: User provisioning to Entra ID

Introduction

This article describes our one-way connection from Leapsome to Microsoft Entra ID for user provisioning.

User provisioning from Leapsome to Entra ID requires employee attributes that are only available in Leapsome HRIS accounts. If you don't use Leapsome HRIS please note that there may be limitations.

It is possible to:

• Authenticate a connection between Leapsome and a Microsoft Entra ID tenant, with our partner Kombo managing the authentication.
• Define mappings between Leapsome user properties and both default and extension properties in Entra ID.
• Create a Leapsome workflow that triggers on user events (such as property updates) and creates or updates users in the connected Entra ID tenant.

Authentication

Currently, authentication is supported through a service user, meaning all actions from Leapsome will be executed under that service user's credentials and the permissions assigned to it.

The following Graph API endpoints are called - either indirectly via Kombo or directly via Kombo’s passthrough API. The service user will require the specified permissions to make the calls.

• For user creation: User.ReadWrite.All, Directory.ReadWrite.All
• For user update: User.ManageIdentities.All, User.EnableDisableAccount.All, User.ReadWrite.All, Directory.ReadWrite.All
• For reading users: User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Data formatting

Leapsome property values are pushed directly to the Entra ID tenant without any formatting or processing. Any required processing must be done externally within a customer's own system.

There's a fixed mapping between the Leapsome user Lifecycle status and the account's enabled/disabled state in Entra ID.

Users will be created/updated as enabled in Entra ID with these lifecycle statuses:

• Active
• Offboarding

Users will be created/updated as disabled in Entra ID with these lifecycle statuses:

• Hired
• Garden Leave
• Terminated
• Deactivated
• No status set / any other status

Other notes

• The Leapsome username field (email address) is used as the initial identifier for users in Entra ID.
  • If a user has not been synced from Leapsome to Entra ID before, we will look them up using their username to search for the user by their Entra ID User principal name.
  • If a matching user is not found then one will be created in Entra ID.
  • Following this initial sync, the user’s entra ID unique user Object ID will be used to identify the user, meaning if their User principal name changes, the sync between the Leapsome and Entra ID will continue.
• Users can only be synced to Entra ID when their email domain matches the domains supported by the Entra ID tenant—syncs will fail for non-matching domains.
• Only single-valued extension properties (with isMultiValued:false) are supported. Syncing array extension properties will fail.
• Newly created users are created with a randomly generated 12-character one-time password containing at least one lowercase letter, uppercase letter, number, and symbol. These passwords are not stored or distributed by Leapsome. The Entra ID tenant owner will need to reset the passwords and distribute new OTP to the users.
• While we've implemented error handling for common issues, the downstream APIs may return vague or poorly documented errors. If you see generic messages like "Failed to create/update user," "Failed to get user," or "Failed to create user," please notify us to help improve error handling.
• As of now, when Leapsome attributes reference other Leapsome entities (e.g., Primary manager referencing another user), only the Leapsome ID of that entity will sync, not its properties (e.g., name). This may be revised in future versions.

Configuring the connection between Leapsome and Entra ID

As an administrator user go to Settings → HRIS Integrations → Outbound Provisioning → Microsoft Entra ID (formerly Azure Active Directory). The following modal will open

Click authorize connection, this will request the authorization connection modal from Kombo, where Kombo will list the permissions required, and then allow you to log in with your service user.

Sign in with your service account user. You will then be shown a modal allowing you to configure the mapping from Leapsome fields to Entra ID default / custom fields.

Note - the first_name and last_name properties are required & fixed values in order to create users. It is recommended you map them from the Leapsome First Name and Last Name properties, although you could pick other properties if you have a different set up.

• Configure the other attribute mappings as required.
• Enable the integration.
• Update the integration settings.

Configure the workflow to trigger the push of user data from Leapsome to Entra Id

Next we need to configure a workflow that triggers when any of these attributes are updated, such that changes to those attributes are pushed to Entra ID.

To do this an admin must go to Settings → Workflows → New Workflow

Configure the workflow to be triggered on Employee Updated events, specifying the mapped attributes as attributes to watch for changes

Create one step with Create / update user in Entra ID as the step type, executed immediately on the Employee Updated event trigger.

Triggering an initial sync for all users

We may then want to push all users to Entra ID, so they are provisioned immediately instead of waiting for the user to be updated to trigger the sync. This can be done by an admin from the employee list screen, by selecting all employees and enrolling them in the created workflow.

Viewing the result of a user sync

Whenever the workflow is triggered for a user - when one of the watched properties is updated, they will be enrolled in the workflow.

You can view the status of that enrollment in the workflow details page as an administrator, or on that users profile in the workflows tab.

If the sync fails, the workflow will be ‘Blocked’, and you may make changes to the user / integration settings / Entra ID tenant and then ‘Retry’ the workflow step.