Azure Active Directory

 

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.

Note
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
  • Email
  • Termination date
  • Status
  • Created at (this is the date on which the employee profile was created and is required for the initial synchronization)

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

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

Note
To authenticate Azure AD, you must have Global Administrator rights in Azure AD and keep these rights as long as the integration is active.

settings-marketplace-azure-create-authentication_en-us.png

 

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 "john.doe@demo.com". 

Note
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. johndoe_12345@demo.com).

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.

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

Note
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. Initial Sync

As soon as the integration is set up, the initial sync 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, 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 ID attribute field in Azure AD.

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

Note
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 Azure AD via the user provisioning workflow, regardless of whether they already have an Azure AD user profile.

 

2. User Provisioning

Once an employee is created in Personio, the integration will automatically create a matching 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.

Notes
▶︎ To create a profile in Azure AD, 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 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.

Notes
▶︎ 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.

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

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

Example
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.
  • Attribute write-back
    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.

 

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.

 

Comments

0 comments

Article is closed for comments.

    Topics of this article