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.

Note: 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.


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.


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". 

Note: 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.

Tip: 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. 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.

Note: The "User provisioning" workflow only allows you to create a new employee. Their profile will be populated only with the following "Update user" workflow.

The user provisioning 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.


2. User Updating

Every time a Personio attribute that was mapped during the setup process is updated (a role change or a department change, for example), the corresponding Okta user will be automatically updated.


3. 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.).

The user is not deleted and their details and connected services are still accessible.


4. Initial Sync

If you were using Okta before integrating it with Personio, it is likely that you already created users in Okta corresponding to your Personio employees. In this case, the synchronization will not be automatic. To pass the respective Personio employee ID to existing Okta users, the integration will try to map the Username 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.
  • For users that don’t have a matching employee, the customer needs to manually identify the matching employee in Personio, get their employee ID (= the number at the end of the URL of the employee profile), and paste it into the Employee Number attribute field in Okta.


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