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
- Step 4. Set the recommended provisioning options in Okta
- Field Mapping
- FAQs
- Okta Reference content
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, and follow the step-by-step guide in Okta displayed on the screen.
Once completed, click Connect.
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.Step 4. Set the recommended provisioning options in Okta
Once Deel and Okta are connected, review the provisioning options in Okta. How you set them up is up to you. The settings below are what Deel recommends if you want Deel HR to be the source of truth for your workforce data.
To find them, go to the Okta Admin Console, open Applications > Applications, select the Deel app, then choose Provisioning > To Okta. For a full walkthrough of this page, see Okta's guide to editing app provisioning settings.
| Setting | Recommended | What it does |
|---|---|---|
| Schedule import | On (hourly) | Okta checks Deel for changes every hour and applies them. Hourly is the most frequent schedule Okta offers. If you turn it off, new hires, updates, and departures in Deel only reach Okta when an admin runs an import manually. See Okta's provisioning settings guide. |
| Okta username format | Custom: appuser.userName | Uses each worker's work email from Deel as their Okta username. See the FAQ on usernames below. |
| Allow Deel to source Okta users | On, if Deel is your source of truth | Lets Deel data take priority over other data for matching Okta users. Learn more in Okta's guide to profile sourcing. |
| When a worker is deactivated in Deel | Deactivate the user in Okta | Offboarding in Deel also removes access in Okta. If you later reactivate the worker in Deel, for example, when they move to a new contract, you can ask Okta to reactivate them too. |
| Attribute mappings | Apply on create and update | When a worker's details change in Deel, Okta updates them. "Create only" keeps the data as it was when the account was first created. Set this on each attribute you map (see Step 5). Learn more about attribute mappings in Okta. |
To check your setup, open the Assignments tab in the Deel app, select one user, and click Provision User. Then confirm the user's profile in Okta shows the right username and 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?
- 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 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. This matches the recommended setting in Step 4.
-
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.
Step 6: 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 6: 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. To set this up, follow the steps in the Custom fields section above.
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.
Why don't my Deel changes show up in Okta right away?
Okta pulls data from Deel on its own schedule, and the most frequent option is once an hour. Deel doesn't push changes to Okta. If you need an update sooner, go to the Deel app in Okta and run an import manually. To make sure imports run automatically, turn on Schedule import (see Step 4).
What if I use more than one identity source, like Active Directory or Workday, alongside Deel?
This works, but plan it carefully. If the same person exists in Deel and in another source, Okta uses profile source priority to decide which system wins and which fields get overwritten. Before you turn on Deel as a source, decide which system should take priority for each field, and test with a single user first. If you only use Deel for a group of workers, such as contractors, make sure those workers don't also exist in your other sources. To set the order, see Okta's guide to prioritizing profile sources.
Okta Reference content