In this article, we explain how to integrate the Identity and Access Management (IAM) tool Azure Active Directory (Azure AD) 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 Azure AD?
This integration facilitates your company's on-and offboarding processes by automatically synchronizing any changes in the employee's information in Personio (role or department changes, for example) with their matching user ID in Azure AD. It automatically updates Azure AD with up-to-date information from Personio to manage the different access rights or equipment given to employees.
The synchronization only works from Personio to Azure AD. When you update information in Azure AD, this information is not automatically synchronized in Personio.
How can I set up the Integration?
To set up an integration, follow the detailed steps below:
1. Requirements for a Successful Integration
- You need to have an Administrator role or have an editing right for Personio Marketplace (Settings > People > Employee Roles > Access rights > Account configuration > Marketplace integration) in Personio.
- You also need to have global administrator rights for your Azure AD tenant.
2. Generate new API Credentials
You need to generate new API credentials for this integration in Personio via Settings > Integrations > API Credentials. Click Create new 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 Azure AD to Read at least the following employee attributes:
- First name
- Last name
- Termination date
- Created at (this is the date on which the employee profile was created and is required for the initial synchronization)
The following attributes are currently not supported: Cost center, Office phone.
3. Find Azure AD in the Marketplace
The Azure AD integration can be implemented directly within Personio. To find this integration in Personio, go to Marketplace > Microsoft Azure AD. Alternatively, you can go to Workflow Hub > Boost with Integrations > Azure AD. 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 Azure AD
Click Authenticate Azure AD, paste the Tenant ID from Azure AD into the field Directory ID, and click Create.
To authenticate Azure AD, you must have Global Administrator rights in Azure AD and keep these rights as long as the integration is active.
5. Authenticate Personio
Authenticate Personio by entering the API credentials (Client ID and Client Secret) that you generated in Step 2 for this integration (in Settings > Integrations > API Credentials), and click Next.
6. Define Login Schema
Choose the format for the User Principle Name (UPN) in which new logins will be created. This is generally the business email address, for example "email@example.com".
In case an employee with the same values for the chosen attributes is added, Azure AD creates a profile with the UPN schema UPNBeginning[Separator]UPNEnd_EmployeeID@domain (e.g. firstname.lastname@example.org).
Create the UPN schema, by first choosing a UPN 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 UPN End (e.g. "Last name") and select a Preferred Azure AD Domain (e.g. "demo.com"). Click Next.
If you prefer not to add a Separator and UPN End, enter None for both options and make sure you have additionally selected Entire field or First letter for the UPN End.
7. Map Attributes
Choose the Azure AD attributes you wish to map with the Personio attributes.
All of your attributes in Personio can be mapped to any of the Azure AD system attributes, but they cannot be mapped to Azure AD custom attributes.
8. Finish the Configuration
By clicking on the Finish button, your Azure AD integration is activated. From the Personio Marketplace, you can edit the mapped attributes at any time or deactivate the integration.
On-, Offboarding and Role Change Workflows With Azure AD
1. User Linking
As soon as the integration is set up, the user linking workflow will activate. If you have already created users in Azure AD corresponding to your employees in Personio, the integration will try to pass the respective Personio employee IDs to the Azure AD user profiles by mapping the UPN attribute in Azure AD to the Email attribute in Personio:
- If there is a match, the respective Personio employee ID is written in the employee ID attribute field in Azure AD. This user will now be taken into account for the user updating and the user deprovisioning workflows.
- If there is no match, the user provisioning workflow will activate.
This workflow also applies for users that are created, either manually or via an import, after the integration setup date.
The integration only tries to link Azure AD profiles that are not inactive.
2. User Provisioning
If the Email attribute of an employee in Personio does not match a UPN attribute in your Azure AD account, the integration will automatically create a new user profile in Azure AD. During this step, Personio transfers the employee ID to the respective profile, triggers the default password creation process and creates the UPN in Azure AD.
This UPN needs to be used as the user login in Azure AD. You can create the UPN schema according to your needs as described above in step 6. Define Login Schema.
▶︎ To create a profile in Azure AD, the employee in Personio needs to have the attributes First name, Last name and Email filled in, cannot have a termination date, and cannot be inactive.
▶︎ This first user provisioning workflow will create the user in Azure AD, but it's the user update workflow that will populate the profile.
3. User Updating
The Azure AD 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 Azure AD. This change of information can then be used by Azure AD to grant or revoke access rights to specific tools.
▶︎ This workflow requires the Employee ID to be in the user profile in Azure AD.
▶︎ Changes are only transferred from Personio to Azure AD. If you manually change an attribute in Azure AD, this is not automatically updated in Personio.
During the attribute mapping process between Personio and Azure AD, the system attribute Department was mapped between Personio and Azure AD. An employee moves departments, from the Customer Support department to the Sales department. The HR Manager makes this department adjustment in Personio. Azure AD automatically receives a notification of this change and revokes the employee's access rights to the company's customer support tool (e.g., Zendesk), and grants them access to the company's CRM tool (e.g., Salesforce).
4. User Deprovisioning
Once an employee passes their termination date in Personio, Azure AD revokes their access permission, and the employee can no longer log in to any of their accounts.
Users will not be deleted. This allows you to keep access to their details and their connected services such as email inboxes, etc.
An employee will leave the company on Sep 30th and the HR Manager has set the termination date in Personio for this day. On Oct 1st, this employee's access rights to Azure AD will be blocked, and they will no longer be able to log in to any of the company's systems.
Current Limitations of the Integration
Hybrid Azure / on-prem AD setups
Personio only supports full cloud setups – no cloud/on-prem hybrid setups – which means the integration only allows the creation, update and deactivation of users in Azure Active Directories.
Assigning users to groups
The integration only allows users to be created. Users are not added to groups.
All attributes selected in the mapping table will be sent from Personio to Azure AD – the integration does not currently support a sync from Azure AD to Personio.
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.