Identity and access management
Lucca to Entra ID integration: Microsoft accounts from Lucca, with the work address back in Lucca
With an integration between Lucca and Microsoft Entra ID, every new employee from Lucca gets a Microsoft account with job title, department, business establishment and manager, and the account is blocked as soon as the employment in Lucca has ended. The new Microsoft address goes back to Lucca as the professional email address.
What the integration does
Organisations that use Lucca for HR, often because of a French branch, and Microsoft 365 for their workplace create accounts in Entra ID by hand. The work address then still has to go into Lucca, and the end of an employment only reaches IT when someone passes it on.
- In Lucca the administrator creates an OAuth client for KoppelHet with read rights on employees and employments and write rights on employees for the email address.
- KoppelHet registers a webhook endpoint in Lucca for employee and employment notifications.
- An employee with status upcoming gets a disabled account, which is enabled on the first day of the employment.
- The Microsoft address goes back to the email field in Lucca.
- When the status becomes deactivated, KoppelHet blocks the account and sets the leave date in Entra ID.
What to watch for with Lucca and Microsoft Entra ID
- Lucca calculates an employee's status from their employments, as upcoming, active or deactivated. Only an employee with a current employment can sign in to Lucca itself. KoppelHet follows the same status for the Microsoft account, so HR controls access to both with one action in Lucca.
- For each employee Lucca points to the job position that applies now, or for a new colleague the next one. Job title, department, establishment and manager are attached to that position. KoppelHet reads them there, so a new colleague already has the right department and manager in Entra ID before the start.
- In Lucca the legal entity follows from the establishment of the first job position. KoppelHet uses the entity for the company name in Entra ID and the establishment's country for the usage location, which Microsoft needs before a licence can be assigned to the account.
- The professional email address can be written in Lucca through the API, but Lucca refuses some domains. KoppelHet writes the Microsoft address back to Lucca and reports it to HR if Lucca refuses the address, instead of skipping it silently.
- Lucca sends a notification with a three-second timeout and tries at most five times within about a day. KoppelHet confirms each notification immediately and processes it afterwards, and compares all employees with Entra ID every day, so a departure does not depend on a single notification.
- Lucca allows fifty requests per minute per environment, shared by all integrations, and a test environment on another domain has its own limit. KoppelHet fetches job positions together with the employee and tests in the test environment first, so payroll or leave integrations are not slowed down.
- Lucca is widely used by organisations with French colleagues, with names such as Hélène or François. Entra ID accepts accents in the display name but not in the local part of a userPrincipalName. KoppelHet converts accents for the address and keeps the display name as Lucca has it.
This integration is also part of joiner, mover, leaver.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Does this also work with on-premises Active Directory?
Yes, we build that integration too, with a small program in your network.
Does the integration read salaries or leave in Lucca?
No. Only employees, employments and job positions; the email address is the only thing KoppelHet writes in Lucca.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Lucca API (v5, header Api-Version 2024-11-01) with OAuth 2.0: employees (status upcoming/active/deactivated, email writable with scope employees.readwrite, remoteId unique), employments (start.date, end.date, legalEntity), job-positions (jobTitle, department, businessEstablishment, manager). Webhooks employee.created, employee.updated, employment.created, employment.updated and employment.deleted; three-second timeout, up to five attempts in about 24 hours, events kept for two months. Limit 50 requests per minute per tenant, 429 with Retry-After.
- To Entra ID through API-driven inbound provisioning (POST /bulkUpload with SCIM, requires Entra ID P1 or higher) or Microsoft Graph (user with employeeId, givenName, surname, userPrincipalName, jobTitle, department, officeLocation, companyName, manager, usageLocation, employeeHireDate, employeeLeaveDateTime and accountEnabled).
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Lucca | Field in Microsoft Entra ID | Notes |
|---|---|---|
employee.id | employeeId | At most 16 characters in Entra ID |
givenName en familyName | givenName, surname en displayName | |
Naamgevingsregel | userPrincipalName en mailNickname | |
applicableJobPosition.jobTitle | jobTitle | |
applicableJobPosition.department | department | |
applicableJobPosition.businessEstablishment | officeLocation | |
applicableJobPosition.manager | manager | |
employment.legalEntity | companyName en usageLocation | |
employment.start.date en end.date | employeeHireDate en employeeLeaveDateTime | |
userPrincipalName (Entra ID) | employee.email |
Related
Lucca → Active Directory
Lucca to Active Directory integration: accounts in your own domain based on Lucca
Lucca → ADP iHCM
Lucca to ADP iHCM integration: fixed and variable pay from Lucca Compensation to Dutch ADP payroll
Lucca → AFAS Profit
Lucca to AFAS integration: employees and pay of the Dutch entity from Lucca in AFAS
ASLucca → Arbodienst (SIVI)
Lucca to the occupational health service via SIVI: confirmed sickness per half day as absence reports