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.
- Under Configuration, fill in the fields as described below.
| Field | Details |
| Button display text | Enter the text you want to appear on the login button, for example, “Continue with [your text]”. If you leave it empty, it displays “Continue with SSO” by default. Note that custom text isn't translated. |
| 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 "https://graph.microsoft.com/oidc/userinfo" 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. |
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: