This article explains how to integrate Okta with Personio. When connected, Okta facilitates the onboarding and offboarding of employees and relevant changes in employee information. The integration automatically updates Okta with up-to-date information from Personio to manage the different access given to employees through Okta.
The synchronization only works from Personio to Okta. When you update information in Okta, this information is not automatically synchronized in Personio.
Pre-requisites for a successful integration
Before beginning the integration process, ensure the following is in place:
- You have an admin role or editing rights for Marketplace Integration and API in Personio via Settings > People > Employee Roles > Access rights > Account configuration > Marketplace Integration and API.
- You have the Okta API token, generated by your Okta administrator.
- The Tray.io, Inc checkbox is activated via Settings > Support > Plan & Billing > Data Protection Information.
- To create a profile in Okta, the employee profile in Personio must contain the First name, Last name, and Email attributes.
Connect and authenticate Okta
Set up the Okta integration directly in Personio's Marketplace with the Configuration Wizard. This requires you to have an Okta API Token and Domain which you enter in Personio. Follow these steps:
- Go to Marketplace in Personio, then search for and select the Okta integration.
- Click Connect to open the Configuration Wizard.
- Enter your API Token (the token value generated in your Okta Admin Console) and Domain. If you have multiple domains, choose the domain that relates to Personio. You can only use one domain for this integration.
- Click Next to go to step two of the Configuration Wizard to Authenticate Personio.
Step two of the Configuration Wizard requires you to grant the Okta integration access to the necessary Personio data. Follow these steps:
- Review the permissions that the Okta integration requires.
- Click Next to go to step three of the Configuration Wizard to define the login schema.
Personio allows Okta to Read at least the following system attributes:
- First name
- Last name
- Hire date
- Termination date
- Created at (this is the date on which the employee profile was created and is required for the initial synchronization)
You can review the granted permissions after the setup process by going to Marketplace > See connected integrations. The button is in the top-right corner of the Marketplace page.
Define login schema
Step three of the Configuration Wizard requires you to choose the format for the Login schema in which new logins will be created. Follow these steps:
- Choose Login Beginning
- Add a Separator
- Choose Login End (If you prefer not to add a Separator and Login End, enter None for both options and make sure you have additionally selected Entire field or First letter for the Login End.)
- Enter Preferred Okta Domain
- Click Next to go to step four of the Configuration Wizard and Map attributes.
In case an employee with the same values for the chosen attributes is added, Okta creates a profile with the Login schema: "LoginBeginning[Separator]LoginEnd_EmployeeID@domain" (for example: firstname.lastname@example.org).
Step four of the Configuration Wizard requires you to choose the Okta attributes you wish to map with the Personio attributes. In this step, you can also decide if you want to automate the activation of users on the hire date. Follow these steps:
- Review all the attributes and ensure that each Personio attribute matches the corresponding Okta attribute.
- Click Add new attribute to include more attributes.
- Click Finish.
The integration setup is complete.
Once the integration is set up, the user linking flow begins. It maps the primary email attribute in Okta to email attributes in Personio.
- If the email attribute in Personio matches the primary email attribute in Okta, the integration adds the corresponding Personio employee ID to the Employee Number field in Okta.
- The employee ID becomes the connector that the integration considers in all future user updating and user deprovisioning workflows.
- If there's no match, manual mapping is required. See Map profiles manually.
Matching Okta profiles with an "Inactive" status aren't considered in the initial user linking process.
Map profiles manually
Unmatched profiles require manual mapping. Follow these steps:
- Identify the profile in Okta that corresponds to an employee profile in Personio.
- Open the employee profile in Personio and locate the system-generated employee ID.
- Go to the relevant employee profile in Personio.
- Copy the number at the end of the employee profile URL.
- Paste the number in the Employee Number attribute field in Okta.
- Personio profiles that were not matched in the initial sync are provisioned in Okta.
- The integration transfers the Personio employee ID to the Employee Number field in the Okta profile, and creates the Username for the user, according to the Login schema you set. (See Define login schema). The user updating workflow populates the profile.
For provisioning to happen, the employee profile in Personio must:
- have the First name, Last name, and Email fields filled.
- not have a termination date.
- not have an "Inactive" status.
Umlauts in names are transformed for the UPN in Microsoft Entra ID according to your billing country. For DACH region customers (for example, Germany), umlauts are transformed to their alternative spelling: ä → ae, ö → oe, ü → ue, ß → ss. For all other countries, umlauts are removed: for example, ä → a.
For this workflow to run successfully, the Employee ID must be in the Okta user profile.
Every 30 minutes, Okta runs the user updating workflow to check if any attributes mapped during the setup process have changed in Personio. If an attribute changes, it automatically updates the mapped attribute in Okta.
This change information can be used by Okta to grant or revoke access rights to specific tools based on the changes. Changes are only transferred from Personio to Okta. If you manually change an attribute in Okta, it doesn't automatically update in Personio.
Changes are only transferred from Personio to Okta. If you manually change an attribute in Okta, this is not automatically updated in Personio.
Once an employee’s Status attribute in Personio changes to Inactive, the user's status in Okta changes from "Active" to "Deactivated". You can manually change the Status attribute in Personio, or it will automatically change when an employee passes their termination date.
The employee can no longer log in to their accounts, but the user is not deleted. This helps you maintain access to their details and connected services like email inboxes.
To find out more about automating your identity and access management by integrating it with Personio, read our Help Center article Identity and Access Management.