Integrate an Authentication Provider with Personio

 

This article explains how to integrate an existing authentication system, for example, Google Single Sign-On (SSO) or OAuth (Open Authorization) 2.0, with your Personio account.

 

1. Google Single Sign-On (SSO)

If Google Single Sign-On is activated, all employees whose Google-based email addresses are stored in their employee profiles in Personio can log in to their Personio accounts via Google authentication. 

To activate Google SSO, follow these steps:

  1. Go to Settings > Integrations > Authentication
  2. Open the tab Google Auth.
  3. Click on (Edit), and select the Yes checkbox.
  4. Click Submit.

settings-integrations-authentication-google_auth_en-us.png

When your employees launch Personio, they will see confirmation that Google SSO is enabled. To log into Personio, an employee simply needs to click on Login with Google

login-google-sso_en-us.png

Note
As your employees will be able to log into Personio from the time SSO is activated, you should activate Google SSO only after your Personio account has been fully implemented. Access to Personio employee accounts is then controlled via Google. As soon as Google SSO is enabled, it will no longer be possible for an employee to log in with the Personio username and password.

 

2. OAuth 2.0 

Note
It is recommended that you work with an IT administrator to implement this type of authentication.

Personio supports login via the OAuth 2.0 protocol. This provides for secure and standardized management of access to applications.

To configure the OAuth 2.0 settings directly in Personio, follow these steps:

  1. Go to Settings > Integrations > Authentication.
  2. Open the tab OAuth 2.0.
  3. To edit the configuration settings, click on (Edit).
    Note: All the data that you need to enter into the input fields to configure the settings must be taken from your OAuth provider settings.

    settings-authentication-configuration_en-us.png
  4. In the Authorization URI field, enter the Authorization URI. Users will be forwarded to the Authorization URI page when they click Login with OAuth.
  5. In the Token URI field, enter the Token URI. Personio will call this endpoint to get a token to verify that the credentials entered are correct. 
  6. Under Userinfo URI, ensure that GET is selected from the drop-down menu.
  7. Paste the Userinfo endpoint into the Userinfo URI 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, ensure that you deselect the Skip reading entities from ID token checkbox, making it possible to implement OAuth with Active Directory Federation Services (ADFS). 
  8. In the Scopes field, enter the desired scope. This field specifies how user information is transferred to Personio. For many OAuth providers, the correct value for this field is "openid, email".
  9. In the Client ID field, enter the client ID that will be used for authentication.
  10. In the Client secret field, enter the secret of the client used for authentication
  11. Under Claim Field, select the field in your OAuth provider 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. You can choose between "email", "unique_name", "sub" and "upn".

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

  12. Optional: In the Authentication Context Class Reference field, enter the authentication context class reference. This reference is equal to the acr_values field within your OAuth provider. This reference can be used to set up additional processes on the side of your identity provider, such as two-factor authentication.
  13. Click on Submit.

 

Configure the Redirection to the Callback URI in your OAuth Provider

After you have submitted the configuration settings, you then need to configure the redirection to the Callback URI  in your OAuth provider settings. The Callback URI is listed under Provider settings in Personio.

 

settings-authentication-oauth_2.0-callback_uri_en-us.png

 

Enter the Callback URI listed under Provider settings in Personio into the relevant input field in your OAuth provider settings.

If users will log in to your OAuth provider via the Personio mobile app, you will also need to whitelist the following callback URL as a client with your OAuth provider:

https://auth.personio.de/providers/oauth/callback

To verify that authentication has been set up successfully, click on Test configuration.  

settings-authentication-oauth-test-configuration_en-us.png

You will be asked to sign in to your OAuth provider. To help with your troubleshooting, the exact message that will display if there are errors will be shown.

Note
Employees will only be able to log in via OAuth if the email address that is transferred in the attributes "email", "unique_name", or "sub" from your OAuth provider is the same as the one saved in the employee's Email field in Personio.

 

Optional OAuth Authentication Enforcement

After setting up OAuth, login via your authentication provider is optional. Your employees can choose whether they wish to log into Personio using their Personio access data or via OAuth. If you want to make it mandatory for all employees to log in via OAuth, activate this setting by clicking on the Enforce OAuth button.

settings-authentication-oauth-enforcement_en-us.png

 

3. LDAP/Active Directory via OAuth2

Note
It is recommended that you work with an IT administrator to implement this type of authentication.

If you want to integrate your Active Directory with your Personio account, you need to implement this option via an identity provider. The identity provider serves as an OAuth interface between your Active Directory and Personio.

The WSO2 Identity Server is a good choice of tool for identity and access management. A free download is available. 

If you are already using one of the following providers, you can also implement your OAuth integration through them:  

 

More Information

 

Comments

0 comments

Article is closed for comments.

    Topics of this article