Identity and access management
Darwinbox to Okta integration: Darwinbox as HR source for Okta, with the work email back in Darwinbox
With an integration between Darwinbox and Okta, every employee from Darwinbox gets an Okta user with job title, department, group company and manager, and is deactivated on the approved last working day. Darwinbox provides its own Okta Workflows connector that can update the email address in Darwinbox; KoppelHet makes Darwinbox the HR source for Okta through the Custom Identity Source and uses that connector or the API for the return path.
What the integration does
Organisations that use Darwinbox as HR system and Okta for SSO often only switch on the Darwinbox app for sign-in in Okta. IT then creates users by hand, and HR has to retype the work email Okta hands out into Darwinbox.
- We request API access from Darwinbox, with a dataset containing the fields Okta needs.
- In Okta we create a Custom Identity Source and a service app for KoppelHet.
- At go-live we link existing Okta users to their Darwinbox user ID.
- After that KoppelHet delivers the changes to Okta hourly in one session, and deactivates leavers on their last working day.
- As soon as Okta has a work email, KoppelHet puts it into Darwinbox through the Darwinbox API or the Workflows connector.
What to watch for with Darwinbox and Okta
- The Okta catalogue lists Darwinbox with a connector and a workflow template. According to Okta, the Okta Workflows connector is built by Darwinbox itself, with support through Darwinbox, and has actions to update user fields and the email address in Darwinbox. An HR import from Darwinbox into Okta is not described in those sources; for that KoppelHet uses Okta's Custom Identity Source.
- Okta treats a HR source's externalId as immutable. In Darwinbox the employee_id can be changed; according to Darwinbox the call that sets the email address also updates employee IDs. KoppelHet therefore uses Darwinbox's internal user_id as externalId and sets the employee_id as an ordinary attribute.
- Darwinbox only returns departure data for a given list of employees, with the status approved, pending or revoked. KoppelHet requests them for the employees from the last round and only deactivates the Okta user on an approved departure, on the last working day. If the departure is revoked, the schedule lapses.
- Darwinbox keeps a list of deleted hires, with date and reason. If Okta has already staged a user for such a person, KoppelHet removes them from the HR source, so Okta deactivates them and no active account remains for someone who never started.
- Darwinbox returns dates in several formats, such as 12-Aug-2011, and in Okta's HR source every field is text. KoppelHet puts hire date and last working day in one fixed format, so group rules in Okta can rely on them.
- Which fields the Darwinbox API returns is decided by a dataset Darwinbox sets up per customer, and API access is only given on request. Fields such as group company, country and manager therefore only come along if they are in that dataset. KoppelHet draws up the field list beforehand with you and Darwinbox.
- A session of Okta's HR source takes two hundred users per delivery, and only one session per source can run at a time. Darwinbox can return all changed employees since a point in time in one call. KoppelHet bundles those changes hourly into one session, so Okta does not get stuck on overlapping sessions.
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
Is the Darwinbox app in Okta not enough?
It handles signing in to Darwinbox. According to the descriptions we found, it does not create and deactivate users in Okta from Darwinbox.
Is a leaver deleted from Okta?
No, Okta deactivates the user. Deleting remains IT's choice.
What if HR revokes a departure?
Then KoppelHet sees the revoked status and the user stays active.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Darwinbox Employee Core APIs (api_key per endpoint with basic auth, or OAuth 2.0 client credentials with a 3600-second token): masterapi/employee with datasetKey and last_modified or date_of_activation; UpdateEmployeeDetails/separationDetails with separation_status (Approved, Pending or Revoked) and a list of employee_ids; UpdateEmployeeDetails/getDeletedEmployees; UpdateEmployeeDetails/update with email_id. Okta Workflows connector by Darwinbox with the actions Update User Attributes and Update Email ID.
- Okta Identity Sources API (Custom Identity Source): create session, bulk upsert of users (200 per delivery), bulk delete on departure or deleted hire (Okta deactivates), one active session per source; externalId immutable; profile attributes as strings only.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Darwinbox | Field in Okta | Notes |
|---|---|---|
user_id | externalId | |
employee_id | employeeNumber | |
first_name, last_name | firstName, lastName | |
Naamgevingsregel | login en email | |
designation_name | title | |
department_name | department | |
Group company | organization en groep | |
direct_manager_employee_id | managerId | |
date_of_joining, goedgekeurde laatste werkdag | Eigen attributen (tekst) en deactiveren | |
email (Okta) | email_id (Darwinbox) |
Related
Darwinbox → Active Directory
Darwinbox to Active Directory integration: domain accounts that follow Darwinbox, per office location
Darwinbox → ADP iHCM
Darwinbox to ADP iHCM integration: CTC changes, extra payments and approved separations to Dutch ADP payroll
Darwinbox → AFAS Profit
Darwinbox to AFAS integration: Dutch employees from Darwinbox in AFAS payroll
ASDarwinbox → Arbodienst (SIVI)
Darwinbox to the occupational health service via SIVI: approved sick leaves as absence reports