Skip to main content

What can we help you with?

Back

Set up single sign-on (SSO) in Personio with Azure Active Directory

 

This article explains how to set up single sign-on (SSO) in Personio with Azure Active Directory (AD).

SSO allows you to connect Personio to an identity provider such as Azure AD or Okta. Personio supports the OAuth 2.0 protocol, an open-source standard for access delegation. When set up correctly, users can carry out an authentication via an identity provider without having to use the credentials provided by Personio.

Notes
▶︎ Setting up SSO with Azure AD does not automatically sync Personio application users to Azure. To do this, you need to set up the integration with Azure separately. Learn more about our integration with Azure Active Directory.
▶︎ Even if SSO is enabled, you still need to send an invitation email to your employees. Otherwise, they will not receive notification emails from Personio.

To set up SSO in Personio with Azure AD, follow the steps below.

 

1. Register and create a new application in Azure AD

Tip
When carrying out this configuration, open the Personio application and Azure AD in separate tabs.

azure_ad-register_application-name-authentication_en-us.png

  1. In the Azure AD admin center, go to Azure Active Directory > App registrations.
  2. To register a new application such as Personio, click New registration.
  3. In the Name field, enter a name for the application, for example "Personio SSO".
  4. Under Supported account types, select the account type that can use the application or access the API.
  5. In Personio, go to Settings > Integrations > Authentication > OAuth 2.0.
  6. Under Provider settings, copy the URL from the Callback URI field. 
  7. Return to Azure AD. Paste the Callback URI that you copied from Personio into the field under Redirect URI.
  8. Ensure that Web is selected from the drop-down menu as the redirect type. 
  9. To register the application, click Register.

A message will display to confirm that the application has successfully been created and you will be taken to the new application.

Tip
If users should be able to log in via the Personio mobile app, you also need to whitelist the following callback URL: https://auth.personio.de/providers/oauth/callback

 

2. Copy URIs to Personio

After you have created the Personio application, follow these steps to copy the Authorization URI and the Token URI from Azure AD to Personio, and to add the Userinfo URI to Personio.

Note
The Userinfo URI has been set by Microsoft: https://graph.microsoft.com/oidc/userinfo. It is not specific to your Azure AD domain. https://graph.microsoft.com is not sufficient.

  1. In the new application that you have created in Azure AD, go to Overview > Endpoints and click Endpoints.

    azure_app-overview-endpoints-oauth_authorization_endpoint_en-us.png
  2. Copy the value in the OAuth 2.0 authorization endpoint (v2) field.
  3. In Personio, go to Settings > Integrations > Authentication > OAuth 2.0.
  4. Under Configuration, click Edit.

    settings-authentication-configuration_en-us.png
  5. Paste the value that you copied earlier from the OAuth 2.0 authorization endpoint (v2) field into the Authorization URI field.
  6. Return to Overview > Endpoints in Azure AD. Copy the value in the OAuth 2.0 token endpoint (v2) field.
  7. Return to Personio. Paste the value into the Token URI field.
  8. Under Userinfo URI, select "GET" from the drop-down menu and paste the Userinfo endpoint "https://graph.microsoft.com/oidc/userinfo" into the field. The Skip reading entities from ID token checkbox is selected by default. This means that user information, specifically the user email address, will be read upon login from the Userinfo URI instead of the token URI.

    Note
    If you want user information to be read upon login from the token URI instead of the Userinfo URI, deselect the checkbox, making it possible to implement OAuth with Active Directory Federation Services (ADFS).

  9. Under Scopes, enter "openid, email".

 

3. Register a new client secret

  1. In the application that you have created in Azure AD, go to Manage > Certificates & secrets.
  2. Select Client secrets.
  3. The Add a client secret drawer is displayed.
  4. In the Description field, enter a name for the client secret and choose the relevant expiry date from the Expires drop-down menu.
  5. Click Add.
  6. A page is displayed showing an overview of the application credentials. Copy the value listed under the Value column.

    azure_ad-manage-certificates_and_secrets-client_secrets_en-us.png
  7. In Personio, go to Settings > Integrations > Authentication > OAuth 2.0.
  8. Under Configuration, click Edit.
  9. Paste the value that you copied earlier into the Client secret field.
  10. Return to Azure AD > Overview. Copy the value that is listed for the Application (client) ID.
  11. Return to Personio. Paste the value into the Client ID field.

 

4. Select the Claim

Under Claim field, select the field in Azure AD where the email addresses of your employees are stored. To validate that an employee exists in Personio, we will check if the value in this field corresponds to the email address used in Personio. Depending on your setup in Azure, you can choose between "email", "unique_name", "sub" and "upn".

azure-claimfield_en-us.png

Tips
▶︎ If you select Use default, we will check the fields "email", "unique_name" and "sub" in sequential order until we find one that contains a value.
▶︎ If the email addresses of your employees are stored in the User Principal Name (UPN) field in Azure, select "upn" here.

 

5. Review and Test

  1. Review the data that you have entered in Personio.
  2. When you are certain that you have entered all the data correctly, click Submit.
  3. To test the OAuth connection, click Perform a configuration test.

You will be asked to sign in to Azure AD. If there are errors, a message will be shown to help with your troubleshooting.

Note
To be able to use SSO, employees need to have user profiles in both Azure AD and Personio. The email address that is entered in Azure AD in the field you have selected under Claim field must match the email address used in Personio.

 

Optional: Enforce single sign-on with Azure AD

After setting up single sign-on with Azure AD, login via OAuth is optional. Your employees can choose whether they wish to log into Personio using their Personio credentials or via OAuth.

If you want to make it mandatory for all employees to log in via OAuth, click the Enforce OAuth button.