This article explains how to set up the Microsoft Entra ID integration with Personio. When connected, the Microsoft Entra ID integration facilitates your company's on-and offboarding processes. It automatically synchronizes changes in employee information in Personio (for example, role or department changes) with the matching user ID in Microsoft Entra ID. It updates Microsoft Entra ID with the latest information from Personio. With this integration, you can manage employee permissions or equipment.

Note:
Automatic synchronization only works from Personio to Microsoft Entra ID. Updating information in Microsoft Entra ID doesn't trigger automatic synchronization in Personio.

Before you start

Before beginning the integration process, ensure the following is in place:

• You have an admin role or edit permissions for the Marketplace Integration in Personio. 
• You have Privileged Role Administrator rights for Microsoft Entra ID. You don’t need to have Global Admin rights. As of October 2024, the integration requires reduced permissions. For details, see review integration permissions.

Connect and authenticate Microsoft Entra ID

Set up the Microsoft Entra ID integration in the Marketplace. Follow these steps:

1. Go to Marketplace in Personio.
2. Search for and select the Microsoft Entra ID integration.
3. Click Connect to open the Configuration Wizard.
4. Enter your Microsoft Entra ID tenant ID.
5. Continue to the next step and authenticate Microsoft Entra ID.

Authenticate Microsoft Entra ID

You need to authenticate Microsoft Entra ID from the Microsoft account linked to it.

1. Follow the steps outlined in the Configuration Wizard.
2. Authenticate Microsoft Entra ID.
3. Continue to the next step and authenticate Personio.

Authenticate Personio

You need to grant the integration access to the necessary Personio data. Follow these steps:

1. Review the permissions that the Microsoft Entra ID integration requires.
2. Continue to the next step and define the UPN schema.

Data transmission

When you set up the integration, you grant Personio the following permissions for data transmission:

• User.ReadWrite.All
• User.Read
• Group.Read.All
• offline_access

For details on each permission, see the Microsoft Graph permissions reference.

Define UPN schema

Choose the format for the User Principle Name (UPN) for creating new logins. This is generally the business email. For example, "john.doe@demo.com". 

1. You have the option to pre-assign email addresses or manually define them via an existing Personio attribute. Alternatively, you can configure the format for automatically generated email addresses by following the steps below.
2. Create the UPN schema by selecting a UPN Beginning from available attributes, such as "First name." Then, define whether to use the entire field or the first letter.
3. Optional: Add a Separator (e.g. ".")
4. Add a UPN End (e.g. "Last name")
5. Select a Preferred Microsoft Entra ID Domain (e.g. "demo.com").
6. Continue to the next step and map attributes.

If you prefer not to add a Separator and UPN End, enter None for both options. Make sure you also select Entire field or First letter for the UPN End.

Note:
In case you add an employee with the same values for the chosen attributes, Microsoft Entra ID creates a profile with the UPN schema: UPNBeginning[Separator]UPNEnd_EmployeeID@domain (e.g. johndoe_12345@demo.com).

Map attributes

Select which Microsoft Entra ID attributes to synchronize with Personio. Follow these steps:

1. Review all the attributes. Make sure each Personio attribute matches the corresponding Microsoft Entra ID attribute.
2. Add more attributes if needed.
3. Click Finish to complete the integration setup.

You can't map all your attributes in Personio to Microsoft Entra ID custom attributes. You can map your Personio attributes to these Microsoft Entra ID system attributes:

• Business Phones
• City
• Company Name
• Country, Department
• Display name
• Employee Type
• Given Name
• Hire Date
• Job Title
• Mail
• Manager
• Mobile Phone
• Workplace Location
• Postal Code
• Street
• Surname

On-, offboarding, and role change workflows

User linking

Once you set up the integration, the user linking flow begins. It maps the UPN attribute in Microsoft Entra ID to the Email attribute in Personio. The integration doesn't link any inactive Microsoft Entra ID profiles.

• If the UPN attribute in Microsoft Entra ID matches the Email attribute in Personio, the integration adds the corresponding Personio "Employee ID" to the Employee ID attribute field in Microsoft Entra ID.  
• The Employee ID becomes the connector for all future user updates and user deprovisioning workflows.
• The system provisions profiles that don't have a matching Personio email and are not inactive in Microsoft Entra ID. 

Review integration permissions

As of October 2024, the integration has reduced the required permissions. If you already use the integration and want to use these reduced permissions, re-authenticate and set the appropriate rights in Microsoft Entra ID. Refer to the pre-requisites for a successful integration section.

Note:
If the integration fails to update a user because they have a more privileged role, assign a higher role to the app. For more information on admin rights, visit Microsoft's documentation on roles and privileges.

User provisioning

If an employee's Email attribute in Personio doesn't match a UPN attribute in your Microsoft Entra ID account:

• The integration creates a new user profile in Microsoft Entra ID.
• Personio transfers the "Employee ID" to the respective profile.
• The integration triggers the password creation process. It also creates the UPN in Microsoft Entra ID.

You must use the created UPN as the user login in Microsoft Entra ID. You can create the UPN schema according to your needs.

To create a profile in Microsoft Entra ID, the employee profile in Personio must:

• Have complete First name, Last name, and Email fields.
• Not have an Inactive status. 

Note:
Umlauts in names change for the UPN in Microsoft Entra ID according to your billing country. For DACH region customers (for example, Germany), umlauts change to their alternative spelling: ä → ae, ö → oe, ü → ue, ß → ss. For all other countries, the system removes umlauts: for example, ä → a.

Connect rehired employees 

When you rehire a former employee, you have two Personio profiles for them: one inactive and one active. Entra ID creates email addresses based on the employee's first and last name, so it tries to create the same email that already exists for the inactive profile. Since the email address already exists, Entra ID cannot complete the user creation process. This blocks the employee's access and prevents them from logging in to any systems.

To fix this, update the Employee ID in Entra ID to match the new Personio profile ID. You can find this ID in the URL when you click on the employee's profile. This way, Entra ID recognizes the existing user and doesn't try to create a new profile.

User updating

For this workflow to succeed, you must enter the Employee ID in the Microsoft Entra ID profile.

Every 30 minutes, Microsoft Entra ID runs the user updating workflow. It checks if any attributes mapped during the setup process have changed in Personio. If an attribute changes, the system updates the mapped attribute in Microsoft Entra ID.

Microsoft Entra ID can use this information to grant or revoke permissions to specific tools. Changes only transfer from Personio to Microsoft Entra ID. If you manually change an attribute in Microsoft Entra ID, this doesn't automatically update in Personio.

Example

A company mapped the "Department" system attribute between Personio and Microsoft Entra ID. An employee moves departments from the Customer Support department to the Sales department. The HR Manager makes this change in Personio. Microsoft Entra ID automatically receives a notification of the change. It revokes the employee's permissions to their customer support tool (for example, Zendesk). It also grants them access to their CRM tool (for example, Salesforce). 

User deprovisioning

Microsoft Entra ID revokes an employee's access permission once their Status attribute changes to Inactive in Personio. You can manually change the Status attribute. It also automatically changes when an employee passes their termination date in Personio.

The employee can no longer log in to their accounts, but the system doesn't delete the user. This helps you maintain access to their details and connected services like email inboxes. 

Limitations

• Hybrid Microsoft Entra ID / on-prem AD setups
  Personio only supports full cloud setups. It doesn't support cloud/on-prem hybrid setups. This means the integration only allows the creation, update, and deactivation of users in Microsoft Entra ID.
• Assigning users to groups
  The integration only allows the creation of users. It doesn't add users to groups.
• Attribute write-back
  The system sends all attributes selected in the mapping table from Personio to Microsoft Entra ID. The integration doesn't support syncing from Microsoft Entra ID to Personio.

Next steps

Learn more about automating your identity and access management by integrating it with Personio.