This article explains how to set up single sign-on (SSO) in Personio with an external identity provider using OpenID Connect / OAuth 2.0.
When you set up SSO, employees log in to Personio through your chosen identity provider. They don't have to log in using credentials. We recommend working with your IT team to complete this setup.
Personio supports other login methods too. For an overview, refer to our dedicated article.
Before you start
- To set up SSO, you need the following permissions:
- An Administrator role in Personio, or
- An employee role with edit permissions for Account configuration > Authentication.
- Make sure you’ve already invited your employees to Personio. They each need to activate their account before they can log in.
Set up the redirection to the callback URI in your identity provider
- Go to Settings.
- In the Security & integrations section, click Security & authentication.
- From the list of login methods, go to OpenID Connect (OIDC) and click Configure.
- Under Provider settings, copy the callback URL.
- Enter this URL into the relevant field in your identity provider's settings.
- You also need to enter this URL into the relevant field in your identity provider's settings:
https://login.personio.com/login/callback
Configure OpenID Connect / OAuth 2.0 in Personio
- In Personio, go to Settings.
- In the Security & integrations section, click Security & authentication.
- From the list of login methods, go to Open ID Connect (OIDC) and click Configure.
Fill in the fields as described below.
Configuration
| Field | Details |
| Issuer | Refer to the section below for more information. |
| Authorization URI | Enter the authorization URI. The system forwards users to the authorization URI page when they click Login with OAuth. |
| Token URI | Enter the token URI. Personio calls this endpoint to get a token to verify that the credentials entered are correct. |
| Userinfo URI |
Select GET from the dropdown menu. Paste the Userinfo endpoint from your external identity provider into the field. The system selects the Skip reading entities from ID token checkbox by default. Upon login, the system reads user information, including the email address, from the Userinfo URI instead of the Token URI. Clear the checkbox if you want it to read user information from the Token URI instead. This enables you to use OAuth with Active Directory Federation Services (ADFS). |
| JSON Web Key Sets URI | Refer to the section below for more information. |
| Scopes | Specify how user information transfers to Personio. For many OAuth providers, the correct value is "openid, email". |
| Client ID | Enter the client ID to use for authentication. |
| Client secret | Enter the client secret used for authentication. |
| Secret expiry date |
Enter the expiration date of your client secret. Personio sends reminder emails to your Account Owners 30, 14, 7, and 1 day before the date you enter. When you update your secret and expiry date, the reminders stop. We recommend you update this field every time you rotate your secret to keep reminders accurate. If your client secret expires, Personio emails your Account Owner steps to regain access to Personio. |
| Claim field |
Select the field in your identity provider with the email addresses of your employees. To validate that an employee exists in Personio, the system checks if the value in this field corresponds to the email address used in Personio. You can choose between "email", "unique_name", "sub", and "upn". If you select Use default, the system checks the fields "email", "unique_name", and "sub" in sequential order until it finds one that contains a value. |
| Authentication context class reference | Optional: Enter the authentication context class reference. This reference is equal to the acr_values field in your identity provider. You can use this reference to set up other processes on your identity provider's side, such as 2FA. |
Login experience
| Field | Details |
| Button display text (optional) |
Enter the text you want to appear on the login button, for example, “Continue with [your text]”. Note that custom text isn’t translated. If you leave this field empty, the login button displays "Continue with SSO" by default. |
| Home Realm Discovery (optional) |
Enter a comma-separated domain list. After configuration, your employees enter their email address on the Personio login page. If their email domain matches any domain in the list, they’re redirected to your identity provider login flow. Use this option if you want to enforce your identity provider login for a certain set of email domains. |
Configure issuer and JWKs URI fields
- The Issuer is the issuer identifier of the authorization server in the authorization response. In this field, enter the value of the issuer field from the .well-known/openid-configuration endpoint of your SSO provider.
- The JSON Web Key Sets (JWKs) URI is the discovery URI to a set of public keys. These keys verify any JSON Web Token (JWT) issued by the authorization server. In this field, enter the value of the jwks_uri field from the .well-known/openid-configuration endpoint of your SSO provider.
You can find the issuer and jwks_uri fields in the discovery document endpoint of your SSO provider. You can usually access this through one of these URLs:
- https://example-provider.com/well-known/openid-configuration
- https://example-provider/oauth2/token/.well-known/openid-configuration
- https://example-provider.com/oauth2/authorize/.well-known/openid-configuration
- https://example-provider.com/v2.0/.well-known/openid-configuration
Review and test
Tip:
If you plan to set your chosen identity provider as the only enabled login method, perform a configuration test first. This prevents you from locking yourself out if the configuration is incorrect.
- Review the data you've entered in Personio.
- Submit your changes.
- To test the OIDC connection, enable the connection and click the Test button.
- The connection redirects you to sign in to your identity provider. If there are errors, a message appears to help with troubleshooting.
Employees can log in through OAuth only if the email address for the attribute "email", "unique_name", or "sub" in your OAuth provider matches the email address used in Personio.
Optional: Enforce SSO with your chosen identity provider
After you complete the configuration, you can enforce SSO with your chosen identity provider. To make it mandatory for all employees to log in through OpenID Connect (OIDC), set it as the only enabled login method.
LDAP / Active Directory via OAuth 2.0
If you want to integrate your Active Directory with Personio, you need to implement this option via an identity provider. The identity provider is an OAuth interface between your Active Directory and Personio.
The WSO2 Identity Server is a good tool for identity and access management. A free download is available.
If you already use one of these providers, you can set up your OAuth integration through them: