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.
Connecting the integration
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
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.
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.
Step 4: Map standard fields
Standard attributes are the foundational identity data points that exist by default in both Deel HR and Okta. Mapping these ensures that basic identity (who the person is and what their role is) is consistent across your organization.
| 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 |
- Log in to your Okta Admin Dashboard.
- Navigate to Applications > Applications and select the Deel app.
- Click on the Provisioning tab.
- In the left-hand sidebar, click To Okta.
- Scroll down to the Attribute Mappings section.
- Click the Edit (pencil) icon next to each attribute to ensure the value coming from Deel is pointed to the correct attribute in Okta.
- Decide how data is treated when it changes:
- Apply on create and update: (Recommended) This ensures that if an employee changes departments or names in Deel, Okta updates automatically.
- Keep existing value: Use this only if you want Okta to ignore any changes made in Deel after the account is first created.
- Click Save at the bottom of the mapping list. To verify, go to the Assignments tab in the Deel app.
- Select a single user and click Provision User to ensure the standard fields populate correctly in their Okta profile.
How to ensure a successful sync?
- 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.
Step 5: Map additional fields
The SCIM integration supports over 30 additional fields. If you want to use these, you must manually prepare Okta to receive this data.
Only profile-level fields can be created. Contract-level fields, for example, are not currently supported in the integration.
- Refer to the All mapped fields table below to identify the field to which you want to map. Note the field's External Name and External namespace.
- In Okta, navigate to Directory > Profile Editor.
- Find the Deel User profile and click Add Attribute.
- Add the information as below:
- External Name: Enter the External Name (Deel ID) field exactly as it appears.
- External Namespace: Enter the External namespace. Example: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.
- Return to Okta > Provisioning > To Okta in the Deel app.
- Scroll to Attribute Mappings.
- Map the Deel source field to your new Okta target attribute.
- Click Save and Force Sync.
All mapped fields
| 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 |
Custom fields
It is possible to create custom fields in the Deel platform and use these in your Okta integration.
Only profile-level custom fields are currently supported
To map to them, follow these steps:
- In the Deel platform, go to Organizational Settings > (Human Resources) Customization > Custom fields.
- Locate the custom field(s) and copy the following information:
- External Name: the External Name (Deel ID) field name exactly as it appears in the Deel platform.
-
External Namespace: Use
urn:ietf:params:scim:schemas:extension:2.0:User.
- Follow the procedure described in Step 5: Map additional fields.
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?
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?
userName property.
Reach out to your Okta representative to obtain support on how
to map this value to your desired property.