System for Cross-domain Identity Management (SCIM) is one of the most widely used protocols for managing users across multiple applications.
The Okta SCIM provisioning integration enables Deel HR clients to automatically sync employee data from Deel into Okta, allowing IT teams to provision users into other applications such as Zendesk, Salesforce, and more.
This article explains how to enable the Okta SCIM integration for Deel HR. The first part of the integration is completed on Deel, while the second part is finalized in Okta.
In this article
- Before you begin
- Step 1. Connect to Okta SCIM in Deel
- Step 2. Connect to Deel in Okta
- Step 3: Finalize the connection
- Field Mapping
- FAQs
Before you begin
You must have:
- A Deel account and be logged in.
- Organization Admin access to Deel.
- A user with Admin permissions in Okta.
Step 1. Connect to Okta SCIM in Deel
- Navigate to your Deel account dashboard.
- Go to More > Apps and search for Okta.
- Click Connect Okta.
Generate the SCIM API Base URL and Organization token.
The SCIM API Base URL is the entry point to the Deel SCIM API, and the API Token is needed for authentication. You may need to manually type in : /scim/v2 at the end of the base URL
Ensure these credentials are saved in a secure location, as they will be required when configuring Okta.
Step 2. Connect to Deel in Okta
Follow the guide in Okta:
Log in to the Okta Admin Console with administrator privileges.
Search for the Deel application in the Okta Integration Network and add it to your dashboard.
Click Add integration.
Navigate to the Provisioning tab within the Deel app settings in Okta.
From the left navigation menu, select the Integration option.
Click the button labeled Configure API integration.
Check the box or toggle for Enable API Integration.
Paste your Organization token (which you should have generated in Deel previously) into the API Token field.
Click Save to finalize the connection.
Step 3: Finalize the connection
Return to the Okta Configuration screen in the setup wizard of the Deel dashboard
Click Connect.
To ensure a worker’s work email is used as their username in Okta, you may need to configure the username format to use
appuser.userName. See the FAQs section below for details.
Field Mapping
The Okta SCIM integration can accommodate the unique way different organizations use the platform. Because some companies use specific custom fields while others do not, the available data can vary between accounts.
While a limited set of attributes is mapped by default, the integration supports adding a wider range of fields from Deel HR, including any custom fields you may have configured.
How to ensure a successful sync?
We recommend these steps:
- Pulling a sample response from the Deel system. This allows you to see exactly which fields are active in your specific organization before you begin.
- Once you have verified your fields, refer to the table below to identify the attributes you need. In Okta, navigate to the Deel HR Profile Editor, click Add Attribute, and configure the fields as specified.
- Configure the Work Email attribute to consistently pull the user's professional email. This must be mapped specifically to the Primary Email field to ensure reliable communication and identity syncing.
- Make sure you are using the To Okta section in the Provisioning tab of the Okta apps section.
Default attribute mappings
This set of attributes is mapped by default for the integration.
| Field Name | External Name | Description | External namespace |
|---|---|---|---|
| user name | userName |
The unique identifier for the user. | urn:ietf:params:scim:schemas:core:2.0:User |
| first name | name.givenName |
The user's legal or official first name. | urn:ietf:params:scim:schemas:core:2.0:User |
| last name | name.familyName |
The user's legal or official last name. | urn:ietf:params:scim:schemas:core:2.0:User |
| primary email | emails.^[primary==true].value |
The email address marked as the primary contact. | urn:ietf:params:scim:schemas:core:2.0:User |
| title | title |
The professional job title of the user. | urn:ietf:params:scim:schemas:core:2.0:User |
| user type | userType |
The category of user (e.g., Employee, Contractor). | urn:ietf:params:scim:schemas:core:2.0:User |
| manager id | manager.value |
The unique ID of the user's manager. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| cost center | costCenter |
The budget code or cost center assigned to the user. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| organization | organization |
The company or organization name. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
All supported attribute mappings
The integration also supports adding a wider range of fields from Deel HR, including any custom fields you may have configured.
| Field Name | External Name | Description | External namespace |
|---|---|---|---|
| user name | userName |
The unique identifier for the user. | urn:ietf:params:scim:schemas:core:2.0:User |
| active | active |
Boolean flag indicating if the user account is currently active. | urn:ietf:params:scim:schemas:core:2.0:User |
| id | id |
The unique system ID for the user resource. | urn:ietf:params:scim:schemas:core:2.0:User |
| first name | name.givenName |
The user's legal or official first name. | urn:ietf:params:scim:schemas:core:2.0:User |
| last name | name.familyName |
The user's legal or official last name. | urn:ietf:params:scim:schemas:core:2.0:User |
| primary email | emails.^[primary==true].value |
The email address marked as the primary contact. | urn:ietf:params:scim:schemas:core:2.0:User |
| work email | emails.^[type=="work"].value |
The user's professional/work email address. | urn:ietf:params:scim:schemas:core:2.0:User |
| home email | emails.^[type=="home"].value |
The user's personal/home email address. | urn:ietf:params:scim:schemas:core:2.0:User |
| other email | emails.^[type=="other"].value |
An alternative email address categorized as "other". | urn:ietf:params:scim:schemas:core:2.0:User |
| title | title |
The professional job title of the user. | urn:ietf:params:scim:schemas:core:2.0:User |
| user type | userType |
The category of user (e.g., Employee, Contractor). | urn:ietf:params:scim:schemas:core:2.0:User |
| address street | addresses.^[type=="other"].streetAddress |
The street address for the "other" address type. | urn:ietf:params:scim:schemas:core:2.0:User |
| address line two | addresses.^[type=="other"].lineTwo |
The second line (suite/apt) for the "other" address type. | urn:ietf:params:scim:schemas:core:2.0:User |
| address city | addresses.^[type=="other"].locality |
The city for the "other" address type. | urn:ietf:params:scim:schemas:core:2.0:User |
| address region | addresses.^[type=="other"].region |
The state or region for the "other" address type. | urn:ietf:params:scim:schemas:core:2.0:User |
| address postal code | addresses.^[type=="other"].postalCode |
The postal or zip code for the "other" address type. | urn:ietf:params:scim:schemas:core:2.0:User |
| address country | addresses.^[type=="other"].country |
The country for the "other" address type. | urn:ietf:params:scim:schemas:core:2.0:User |
| created at | meta.created |
The timestamp indicating when the record was created. | urn:ietf:params:scim:schemas:core:2.0:User |
| last modified | meta.lastModified |
The timestamp of the most recent update to the record. | urn:ietf:params:scim:schemas:core:2.0:User |
| resource type | meta.resourceType |
The type of resource (usually "User"). | urn:ietf:params:scim:schemas:core:2.0:User |
| resource location | meta.location |
The URI/URL of the user resource. | urn:ietf:params:scim:schemas:core:2.0:User |
| department | department |
The name of the department the user belongs to. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| cost center | costCenter |
The budget code or cost center assigned to the user. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| organization | organization |
The company or organization name. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| preferred first name (enterprise) | preferredFirstName |
The user's preferred first name (enterprise extension). | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| preferred last name (enterprise) | preferredLastName |
The user's preferred last name (enterprise extension). | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| manager id | manager.value |
The unique ID of the user's manager. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| manager display name | manager.displayName |
The full name of the user's manager. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| manager email | manager.email |
The email address of the user's manager. | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| enterprise custom field (example) | customFields.custom_a |
Custom (object). Replace custom_a with the client’s key(s). If multiple keys, add multiple rows (e.g., customFields.costCenterAlt).
|
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
| preferred first name (custom ext) | preferredFirstName |
Preferred first name from custom extensions. | urn:ietf:params:scim:schemas:extension:2.0:User |
| preferred last name (custom ext) | preferredLastName |
Preferred last name from custom extensions. | urn:ietf:params:scim:schemas:extension:2.0:User |
| preferred name | preferredName |
The full preferred name of the user. | urn:ietf:params:scim:schemas:extension:2.0:User |
| worker id | workerId |
The internal worker or employee identification number. | urn:ietf:params:scim:schemas:extension:2.0:User |
| start date | startDate |
The user's official start date. | urn:ietf:params:scim:schemas:extension:2.0:User |
| end date | endDate |
The user's official end date or termination date. | urn:ietf:params:scim:schemas:extension:2.0:User |
| birthday | birthday |
The user's date of birth (Format: MM-DD). | urn:ietf:params:scim:schemas:extension:2.0:User |
| hiring status | hiringStatus |
Current status in the hiring/employment lifecycle. | urn:ietf:params:scim:schemas:extension:2.0:User |
| region (custom ext) | state |
The state or region from custom extensions. | urn:ietf:params:scim:schemas:extension:2.0:User |
| country (custom ext) | country |
The country from custom extensions. | urn:ietf:params:scim:schemas:extension:2.0:User |
| is manager | isManager |
Boolean indicating if the user has direct reports. | urn:ietf:params:scim:schemas:extension:2.0:User |
| department hierarchy | departmentHierarchy |
The full breadcrumb or hierarchy of the department. | urn:ietf:params:scim:schemas:extension:2.0:User |
| department external id | departmentExternalId |
The external system ID for the department. | urn:ietf:params:scim:schemas:extension:2.0:User |
| department external id hierarchy | departmentExternalIdHierarchy |
The hierarchy of external IDs for the department. | urn:ietf:params:scim:schemas:extension:2.0:User |
| last date of work | workerTerminationLastDateOfWork |
The actual last day the employee performed work. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure id (Department) | organizationalStructures.^[structureName=="Department"].structureId |
The ID for the "Department" structure. Adjust predicate to client’s canonical structureName.
|
urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure name (Department) | organizationalStructures.^[structureName=="Department"].name |
The name of the "Department" organizational unit. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure hierarchy (Department) | organizationalStructures.^[structureName=="Department"].nameHierarchy |
The name hierarchy for the "Department" structure. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure external id (Department) | organizationalStructures.^[structureName=="Department"].externalId |
The external ID for the "Department" structure. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure external id hierarchy (Department) | organizationalStructures.^[structureName=="Department"].externalIdHierarchy |
The external ID hierarchy for the "Department" structure. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure id (Departments) | organizationalStructures.^[structureName=="Departments"].structureId |
Example for second entry in payload. Adjust as needed for "Departments" plural. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure name (Departments) | organizationalStructures.^[structureName=="Departments"].name |
The name of the "Departments" organizational unit. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure hierarchy (Departments) | organizationalStructures.^[structureName=="Departments"].nameHierarchy |
The name hierarchy for the "Departments" structure. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure external id (Departments) | organizationalStructures.^[structureName=="Departments"].externalId |
The external ID for the "Departments" structure. | urn:ietf:params:scim:schemas:extension:2.0:User |
| org structure external id hierarchy (Departments) | organizationalStructures.^[structureName=="Departments"].externalIdHierarchy |
The external ID hierarchy for the "Departments" structure. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment contract id (active) | employments.^[active==true].contractId |
Returns null if no active employment is found. Use a different predicate if needed. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment title (active) | employments.^[active==true].title |
The job title associated with the active employment record. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment start date (active) | employments.^[active==true].startDate |
The start date for the currently active employment. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment contract type (active) | employments.^[active==true].contractType |
The type of contract (e.g., Full-time) for active employment. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment state (active) | employments.^[active==true].state |
The state/region where the active employment is based. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment country (active) | employments.^[active==true].country |
The country where the active employment is based. | urn:ietf:params:scim:schemas:extension:2.0:User |
| employment team name (active) | employments.^[active==true].team.name |
The name of the team for the active employment. | urn:ietf:params:scim:schemas:extension:2.0:User |
| custom field by name (example) | customFields.^[name=="Custom A"].value |
Custom (array). Replace the name with the client’s label. Add one row per custom field. | urn:ietf:params:scim:schemas:extension:2.0:User |
| custom field by id (example) | customFields.^[id=="78257a21-1af2-4ecc-81a5-d8c2dd22ac0f"].value |
Custom (array). Use stable ID if names are subject to change. | urn:ietf:params:scim:schemas:extension:2.0:User |
FAQs
Can I sync custom attributes/fields from Deel to Okta?
Yes, but it depends on where the attribute is located in Deel. The integration supports two levels of data:
- Profile-level custom attributes: These are supported. You can sync these to Okta by manually configuring your SCIM API mapping in the Okta Profile Editor.
- Contract-level custom attributes: These are not currently supported. Data stored specifically within a worker's contract (rather than their general profile) cannot be synced via the standard Okta SCIM integration.
If you need a specific data point to sync to Okta, ensure it is created as a Personal Profile field in Deel rather than a Contract Detail field.
How can I make sure a worker’s work email is used as their username in Okta?
In Okta, clients can define how usernames are set for users provisioned
via SCIM. To use the worker’s work email from Deel (sent as
userName), you’ll need to configure the username
format in Okta manually.
Here’s how:
- In Okta, go to Applications and select the Deel app.
- Click Provisioning To Okta.
- Under Okta username format, select Custom.
-
In the input field, enter:
appuser.userName.
This ensures that the work email (sent from Deel as
userName) is correctly used as the username for
the Okta account.
Why is userName null in Okta?
The
userName field in Okta is mapped to a worker's
work email in Deel HR. If the work email is not filled in, the
userName in Okta will be null. Enter the worker's
work email in Deel to resolve this issue.
Can I map the work email in Okta?
The Deel SCIM API, which is behind this integration,
returns a worker's work email in the
userName property.
Reach out to your Okta representative to obtain support on how
to map this value to your desired property.