Background information
If you have purchased an Okta license, Lucca provides you with a connector allowing you to synchronize users and groups to your Okta directory. This documentation aims to describe the implementation of this integration by configuring Okta and Lucca.
Supported Features
• Update user attributes
• Import users
• Import groups
• Profile sourcing
[Okta] Integration setup
Go to the Applications menu and click on the "Browse App Catalog" and choose "Lucca" application.
Fill in the required data to configure the integration:
- Base URL: The base url of the application issued when configuring an Okta synchronization from Lucca
- API Token: The authentication API key issued when configuring an Okta synchronization from Lucca
- Import Groups: A checkbox that defines if you want to import groups or not (for group integration to work, this option must also be configured in Lucca)
To retrieve an API Token, you need to set up an Okta synchronization in Lucca by following the instructions below.
In the Provisioning tab, go the To okta menu and click on "Allow SCIM 2.0 Test App (Header Auth) to source Okta users.
[Lucca] Integration setup
In the Authentication, SSO, API menu, go to Okta synchronization and follow the instructions to create a synchronization between Lucca and Okta.
The purpose of activating a synchronization between Lucca and Okta is to deliver an API key allowing Okta to retrieve Lucca users to synchronize them in Okta. This key will be copied / pasted in Okta's synchronization settings. You have to follow the steps on the wizard.
First you have to fill the technical contact field :
The you have to choose the properties you want to synchronize with Okta :
And the groups you want to synchronize :
And finally, Lucca will give you the "Base URL" and "API Token" you have to copy and paste in the okta configuration page:
[Lucca/Okta] User properties setup
The Lucca users API shows the properties attached to a user (for example the contract start date, the contract end date, etc.)
These properties are specific to the Lucca ecosystem and they are not in the SCIM standard. However, it is possible to import them into Okta by setting them up in Lucca and Okta.
[Lucca] User properties setup
In the Authentication, SSO, API menu, go to Okta synchronization. The configuration page allows you to manage the user properties that you want to synchronize with Okta. You can add or remove all simple text properties of the HR directory of your instance. Some properties are mandatory in the SCIM standard. These properties cannot be removed.
Note: Composite datas and multiple occurrences cannot be synchronised with Okta.
[Okta] Attribute / mapping mechanism
What is an attribute ?
There are 2 types of attributes:
- The one present in Okta and which is displayed at the level of a user profile. It is this attribute that can be pushed by Okta towards third-party integration.
- The one returned by the integration API (/ lucca-okta/api/users in our case) and which describes how Okta should retrieve property in the json.
What is mapping ?
The mapping is the connection between the attribute present in Okta and the attribute returned by the integration API.
[Okta] Create an Okta attribute
From the main menu, select Directory → Profile Editor. Then on the left, in the list of filters, select Okta. Then click on Profile.

This page represents all attributes of an Okta user. There are two types of attributes:
-
Native attributes: login, firstName, lastName, etc. found in the SCIM 2.0 standard. These attributes are not editable.
-
Custom attributes

Click on Add Attribute. The following pop-up is displayed and allows you to configure the custom attribute. An attribute is defined by the following fields:
-
a type : string, integer, boolean, etc
-
a human readable name which will be displayed in the user profile
-
a variable name which ideally should match the name of the property present in the json returned by the /lucca-okta/api/users API. This will later make it easier to configure the mapping.

[Okta] Create an integration attribute
From the main menu, select Directory → Profile Editor. Then on the left, in the list of filters, select Apps. Then click on Profile at the "Lucca User" app.
This page represents all attributes of a user on the Integration side. It contains the same types of attributes as in the Okta view, namely native attributes and custom attributes.
Click on Add Attribute. The following pop-up is displayed and allows you to configure the custom attribute. It contains the same information as in the Okta attributes view.
There is an additional field, the External namespace field. It allows you to inform Okta in which schema (at json level) our custom attribute is located.
Indeed, all attributes must be in a schema. There are two schemas in the SCIM standard:
-
urn:ietf:params:scim:schemas:core:2.0:User : associated schema for the attributes of the standard (firstName, lastName, etc.)
-
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User : recommended schema by the SCIM standard for custom attributes (dtContractStart, dtContractEnd, etc.)
Here is an extract from the users json returned by the Lucca.Okta application:
- Framed in blue, we find the 2 diagrams mentioned above.
- Framed in orange, we find the diagram that contains the custom attributes, so the one that we configured previously.
Once the creation is validated, you will find your attribute in the list.
Fill the external namespace field with the value : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
[Okta] Mapping configuration
The last step is to make the connection between the attribute configured on Okta and the attribute configured on the integration side.
From the main menu, select Directory → Profile Editor. Then on the left, in the list of filters, select Apps. Then click on Mappings at the Lucca integration level.
The following pop-up appears
On the left column, you will find the attributes on the Lucca integration side which are mapped one-to-one to the attributes on the Okta side (right column). To configure a new mapping, all you have to do is fill in the missing link in the left column and click on Save Mappings.
You can then apply this new mapping to all users.
Note about Okta to Lucca Synchronisation
Roles and permissions
By default and for security reasons, the Okta connector on the Lucca instance does not allow Okta to modify user data.
If you want to synchronize Okta to Lucca, you need to change the permission of the Okta api key.
In the role administration, you need to add to the Oka API integration api key the permissions needed to modify the user record.
Limitation
- displayName attribute
- On the Lucca environment, there is no RH displayName data associated with collaborators.
- By default Okta expects a displayName attribute whose the path is urn:ietf:params:scim:schemas:core:2.0:User.displayName .
To facilitate your configuration, the displayname attribute is automatically created based on the familyName and givenName.
However, if you have configured an Okta -> Lucca synchronisation on the displayname field, the synchronisation of this field will have no effect. To change the familyName or the givenName, you have to synchronise the familyName and givenName.
- Composite data - Not customizable
Data of type "Composite data - Not customizable" (SPC, calendar, establishments, departments, roles, ...) can be synchronised to Okta, but cannot be synchronise from Okta to Lucca.
Specific Data Type for the environment (Extended Data)
Simple or compound data created for the environment are currently not synchronizable in the Okta -> Lucca direction.
[Lucca] Groups setup
The Lucca. Okta API shows user groups that are loaded into the Okta directory. Four are defined: legal units, establishments, departments and countries. A group returned by the API (/api/groups) includes its member users and a user (/api/users) includes the groups he belongs to. For group integration to work, this option must also be configured in Okta.
You can activate or deactivate the synchronization of each type of group with the Lucca configuration interface:
Groups returned by the Lucca. Okta API are prefixed as follows:
- “LUCCA_LU” for legal units
- “LUCCA_ETS” for establishments
- “LUCCA_DEPT” for departments
- “LUCCA_COUNTRY” for countries
[Okta] Import users
Launch an import
Go to Import tab and then click on Import Now.
When the import is complete, and depending on the configuration chosen, you will need to validate the users to be imported definitively one by one (or by batch via the check boxes).
You can skip this step if the creation / update of users is configured as automatic at the end of the import (see page Provisioning to Okta).
Import result
After confirming the import, go to the Directory / People menu to see the imported users.
Then select a user to see details, including the groups he belongs to.

In the Directory/Groups menu, you can also consult all imported groups and attached people.
Groups are not synchronisable from Okta to Lucca.