In this article, you will learn how to integrate Okta with Personio. You will get an overview of the requirements for the installation of the integration with the Personio employee data API, together with integration installation instructions. 


What can I do With the Integration of Personio and Okta?

This integration facilitates the processes for onboarding and offboarding employees as well as any relevant changes in employee information (e.g. role or department change). It 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.


How can I set up the Integration?

To set up the integration, follow the steps below: 

1. Requirements for a successful integration

  • You need to have an Administrator role or have an editing right for Personio Marketplace (Settings > Employee roles > Access rights > Account configuration > Marketplace integration) in Personio.
  • You need to have the Okta API token, generated by your Okta administrator.


2. Generate new API credentials

You need to generate new API credentials for this integration in Personio via Settings > API credentials. When you select an integration from the drop-down menu, the system usually automatically preselects the system attributes that need to be read or written by the integration. You can add or remove attributes manually if necessary. For more information on how to do this, read our Help Center article on how to generate and manage API credentials.

You need to allow Okta to Read at least the following employee attributes:

  • First name
  • Last name
  • Email
  • Hire date
  • Termination date
  • Status
  • Created at (this is the date on which the employee profile was created and is required for the initial synchronization)


3. Find Okta in the Marketplace

The Okta integration can be implemented directly within Personio. There are two ways of finding the integration in Personio. Go to Settings > Marketplace > Okta. Alternatively, you can go to Workflow Hub > Onboarding > Boost with integrations. Click on the button Connect to start the authentication process.

If you can't find the integration in the Marketplace, make sure the Tray.io, Inc. checkbox is enabled under Settings > Support > Plan & Billing > Data Processing Agreement.

Personio uses Tray.io as a sub-processor to enable the inclusion of certain integrations. No data will be transmitted to Tray.io without using the mentioned integration.


4. Authenticate Okta

Authenticate Okta with an API Token generated from a Global Okta Admin, and a domain. If you have multiple domains, choose the domain that relates to Personio. You can only use one domain for this integration. Click on Next.


5. Authenticate Personio

Authenticate Personio by entering the API credentials you generated for this integration via Settings > API Credentials. Click on Next.


6. Define Login Schema

Choose the format for the Login schema in which new logins will be created. This is generally the business email address, for example "john.doe@demo.com". 

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 (e.g. johndoe_12345@demo.com).

Create the schema, by first choosing a Login Beginning from available attributes (e.g. "First name") and define if the Entire field or only the First letter shall be used. Then optionally add a Separator (e.g. ".") and a Login End (e.g. "Last name") and select a Preferred Okta Domain (e.g. "demo.com"). Click on Next.

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.


7. Map Attributes

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. Click on Finish.


8. Finish the Configuration

By clicking on the Finish button, your Okta integration is activated. From the Personio Marketplace, you can edit the mapped attributes at any time or deactivate the integration. For more information on Personio Marketplace, read our Help Center article Personio Marketplace


Onboarding and Offboarding, and Role Change Workflows with Okta 

1. Initial Sync

As soon as the integration is set up, the initial sync workflow will activate. If you have already created users in Okta corresponding to your employees in Personio, the integration will try to pass the respective Personio employee IDs to the Okta user profiles by mapping the UPN attribute in Okta to the Email attribute in Personio:

  • If there is a match, the respective Personio employee ID is written in the Employee Number attribute field. This user will now be considered for the user updating and the user deprovisioning workflow.
  • If there is no match, you need to manually identify the corresponding employee in Personio, get the system-generated employee ID (the number at the end of the URL of the Personio employee profile), and paste it into the Employee Number attribute field in Okta.

If any of your employees in Personio do not have a profile in Okta, you need to manually create these profiles and add the Personio employee ID to the Employee Number attribute field in Okta.

The initial sync workflow only applies to employees that are already in your Personio account. Newly created employees, either those that have been imported in bulk or added manually, are automatically added to Okta via the user provisioning workflow, regardless of whether they already have an Okta user profile.


2. User Provisioning

Once an employee is created in Personio, the integration creates a new user in Okta with the status Staged. This means that the user is created, but the login doesn’t work until the status is changed to Active. You can automate this activation and set it to the hire date as described above in step 7. Map Attributes.

▶︎ To create a profile in Okta, the attributes First name, Last name and Email need to be filled in the employee profile in Personio.
▶︎ This first user provisioning workflow will create the user in Okta, but it's the user update workflow that will populate the profile.

The user provisioning workflow will transfer the Personio employee ID to the Employee Number field in the Okta profile, and it will create the Username for the user, according to the Login schema which you have set according to your needs as described above in step 6. Define Login Schema.


3. User Updating

The Okta user updating workflow runs every 30 minutes and checks if any attribute that was mapped during the setup process (Step 7) has been changed in Personio in the meantime. If an attribute was changed in Personio, this automatically updates the mapped attribute in Okta. This change of information can then be used by Okta to grant or revoke access rights to specific tools.

▶︎ This workflow requires the Employee ID to be in the user profile in Okta.
▶︎ Changes are only transferred from Personio to Okta. If you manually change an attribute in Okta, this is not automatically updated in Personio.


4. User Deprovisioning

Once the Personio termination date has passed, the status of the user in Okta is changed from Active to Deactivated. The employee can’t use SSO anymore to log in to their systems (Slack account, email account, etc.).

Users will not be deleted. This allows you to keep access to their details and their connected services such as email inboxes, etc.


Current Limitations of the Integration

  • Attribute write-back

All attributes selected in the mapping table will be sent from Personio to Okta – the integration does not support a sync from Okta to Personio at this point.


More Information

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.




Article is closed for comments.

    Topics of this article