Integrate with Personio

Seamlessly onboard new users and sync user updates from Personio to Jumpcloud. The integration creates efficiencies for IT and HR by reducing manual overhead and security concerns related to manual data entry and access based on outdated user data.

Read this article to learn how to configure the Personio Integration.

Prerequisites

  • An administrator account in Personio.
  • A JumpCloud administrator account.
  • Your Personio URL (e.g., https://{mycompany}.personio.de).
  • Read access to the Personio employees’ API and to specific attributes available through that API for a successful integration.
  • For SSO, you must be on the Personio Enterprise plan.

Important Considerations

  • You must set up the integration in the Personio application first and then in JumpCloud.
  • To set up both SSO and Identity Management (IdM), two separate app connectors are needed:
    1. Personio IdM connector using the Personio application connector.
    2. Personio SSO connector using a Custom OIDC App connector.
  • When generating the integration credentials in Personio, leave the default mapped attributes in the scopes. Choosing unneeded attributes can cause the integration to timeout and fail.
  • When importing new users and updates for existing users, the statuses that are classified as inactive for this integration are: Leave and Inactive.
    • Users will not be created in JumpCloud if they have one of these statuses in Personio.
    • When a user’s status changes to either Leave or Inactive, the user will automatically be suspended in JumpCloud.
    • When a user’s status changes from either Leave or Inactive to Onboarding or Active and the reactivationAllowed option is set to true, the user’s state in JumpCloud will change from Suspended to Active.
    • When a user’s status changes from either Leave or Inactive to Onboarding or Active and the reactivationAllowed option is set to false, the user will remain suspended in JumpCloud until you change the user state back to Active.
  • ​​​​​​The timestamp in the User Import Complete email is UTC.

​​​​​​Configuring an integration with Personio

To configure Personio

  1. Log into Personio.
  2. Go to Marketplace from the left navigation panel.
  3. Search for JumpCloud and click it.
  4. Click Connect.
  5. Click Generate new credentials.
  6. Copy the values in your Client ID and your Client Secret.

Tip:

Store this in a secure place, like a Password Manager.

To configure JumpCloud

  1. Log in to JumpCloud Admin Portal.

Tip:

If you would like to use the Staged user state to make it easier to identify users who have been imported and to complete the onboarding process without granting access, complete the following steps. You can learn more about the Staged user state in the Manage User States article.

  • Go to Users > Settings.
  • In the Application / Directory Integrations dropdown, select Staged.
  • Click Save.
  1. Navigate to DIRECTORY INTEGRATIONS > HR Directories.
  2. In the Personio tile, click Configure > + Create New Application.
  3. Enter a Display Label in the General Info tab. Optionally, you can enter a description and adjust the logo shown for the application.
  4. If you are also configuring SSO, we recommend unchecking the Show this application in User Portal option, to avoid confusion for users about which Personio app to select in the User Portal.
  5. Select the Bookmark tab and enter your application URL (e.g., https://{mycompany}.personio.de) in the URL field.
  6. Click activate
  7. Search for and select the Personio app from the list to reopen the configuration.
  8. Select the Identity Management tab.
  9. Expand the Configuration Settings section.
  10. Paste the Client ID and and Client Secret values that you copied when configuring the integration in Personio.
  11. Click Activate and if successful, click save.

Personio User Attributes

Personio Attribute Display Label Personio API Attribute JC systemuser property JumpCloud User Field in Admin Portal Notes
Subcompany subcompany company Company (suggested) Optional
Cost center cost_centers costCenter Cost Center (suggested) Optional (Multiple cost_centers can be assigned in Personio. Only the first cost_center value in the list will be used)
Department department department Department (suggested) Optional
Email email email Company email REQUIRED
Employment Type employment_type employeeType Employee Type (suggested) Optional
First name first_name firstname First Name (suggested) Optional
Position position jobTitle Job Title (suggested) Optional
Last name last_name lastname Last Name (suggested) Optional
Office office location Location (suggested) Optional
Supervisor supervisor.email managerEmail Manager (suggested) Optional
  N/A organization   INHERITED
Email email username Username REQUIRED
Status status state User State CALCULATED
Personio Attribute Display Label Personio API Attribute JC systemuser property JumpCloud User Field in Admin Portal Notes

Configuring SSO for Personio (OAuth) 

Important:

OAuth SSO is only available with the Personio Enterprise plan.

To configure JumpCloud

  1. Access the JumpCloud Administrator Console.
  2. Go to USER AUTHENTICATION SSO.
  3. Click ( + Add New Application ) > Custom OIDC App.
  4. Enter a Display Label in the General Info tab. Optionally, you can enter a description and adjust the logo shown for the application.
  5. Select the SSO tab.
  6. Enter the following information into the fields listed below:
    1. Redirect URIs – https://{mycompany}/oauth/callback
    2. Client Authentication Type – Client Secret Post
    3. Login URL –  https://{mycompany}/oauth/authorise 
    4. Attribute Mapping – email | email 
  7. Click activate.
  8. Copy the Client ID and Client Secret. You will need this in the next section.

Tip:

Store this in a secure place, like a Password Manager.

  1. Click Got It.

To configure Personio

  1. Log into Personio.
  2. Navigate to Settings > Integrations > Authentication.
  3. Enter the following information into the fields listed below:
    1. Authorization URI – https://oauth.id.jumpcloud.com/oauth2/auth
    2. Token URI – https://oauth.id.jumpcloud.com/oauth2/token
    3. Userinfo URI – Get | https://oauth.id.jumpcloud.com/userinfo
    4. Scopes – openid
    5. ClientID – Paste the Client ID you copied from JumpCloud.
    6. ClientSecret – Paste the Client Secret you copied from JumpCloud.
    7. Claim field – email
  4. Click Submit.

Tip:

If you select Enforce oAuth (optional), this will mandate all Personio users to login through JumpCloud.

Authorizing User SSO Access

Users are implicitly denied access to applications. After you connect an application to JumpCloud, you need to authorize user access to that application. You can authorize user access from the Application Configuration panel or from the Groups Configuration panel. 

To authorize user access from the Application Configuration panel

  1. Log in to the JumpCloud Admin Portal.
  2. Go to USER AUTHENTICATION > SSO Applications, then select the application to which you want to authorize user access.
  3. Select the User Groups tab. If you need to create a new group of users, see Get Started: User Groups.
  4. Select the check box next to the group of users you want to give access.
  5. Click save

To learn how to authorize user access from the Groups Configuration panel, see Authorize Users to an SSO Application.

Validating SSO authentication workflow(s)

IdP Initiated

  • Access the JumpCloud User Console.
  • Select the application’s tile.
  • The application will launch and login the user.

SP Initiated

  • Navigate to your Service Provider application URL.
  • You will be redirected to log in to the JumpCloud User Portal.
  • The browser will be redirected back to the application and be automatically logged in.

Importing new users and updates from Personio

To import with the JumpCloud Admin Portal

  1. Log in to the JumpCloud Admin Portal.
  2. Go to USER AUTHENTICATION > SSO.
  3. Search for Personio and click to open its configuration panel. 
  4. Select the Identity Management tab.
  1. There are several settings available for importing users from Personio to JumpCloud.

Warning:

Selected import options will apply to both manual and scheduled imports. 

  1. Expand the Import Users section.
    1. Manual Import – clicking the Start Manual Import button kicks off the process flow for doing an immediate and one-time import of users from Personio to JumpCloud. 
    2. Scheduled Imports (hourly) – enabled by default for all new connectors. The first scheduled import will start within an hour after the new connector is saved. Scheduled imports will then run at the same time every hour as the initial scheduled import.

Important:

Any connectors created prior to the availability of scheduled imports will have this option disabled. To run scheduled imports, you must enable this option.

  1. Selecting the Receive summary email after each scheduled import results in user import complete emails being sent after each hourly import.

Tip:

It's recommended to enable this for the first few scheduled imports to ensure the imports are running correctly. 

  1. In the Import Settings section, you can optionally choose:
    1. Allow reactivation of users on updateChecking the box for this setting will result in the user state changing from Suspended to Active in JumpCloud when a user’s status changes from either Leave or Inactive to Onboarding or Active in Personio.  
    2. Apply Advanced Filters on import (optional). See Personio’s API documentation for available filters

To start a manual import

  1. Expand the Import Users section and click Start Manual Import.
  2. Select one of the following options: 

Note:

If the option selected includes user updates, the following will occur:

  • Any and all changes made to the mapped user attributes in the source application will be made in JumpCloud.
  • Users whose statuses change to one of the defined inactive status will be automatically suspended in JumpCloud.
  • If Allow reactivation of users on update is checked, suspended users in JumpCloud, whose status change from the defined inactive statuses to ones that are not defined as inactive, will have their user state changed back to Active in JumpCloud.
  1. Click Continue.
  2. If you selected the View and select specific new users to import (updates not supported).
    1. Select the users you want to import.

Note:

Free accounts can import unlimited users, but will be prompted to upgrade to a paid subscription after 30 days. Similarly, accounts managed by an MSP, that have a license limit, are only allowed to import users up to their license limit and will be prompted to contact their provider once that limit is reached.

  1. The count of users to be imported will show at the bottom left hand of the list. If this is correct, click Import
  2. Review the information in the results modal.
  3. Click one of the tiles to navigate to the Users page, User Groups page, or Device Groups page or close the modal.​

Note:

If you close this modal, you will return to the Identity Management configuration panel.

  1. You will receive a User Import Complete email with a summary of the import results and a link for downloading a copy of the import results.
  2. You can now connect users to all their JumpCloud resources. Learn more in the Authorize Users to an Application and Connecting Users to Resources articles.

Note:

Imported users must be members of a user group bound to an application  for JumpCloud to manage their identity in and access to the application.

To import with the JumpCloud API

Note:

The import flow using this new API endpoint will only create new users who have an active status in Personio. By default, Leave and Inactive are considered inactive statuses and Onboarding and Active are considered active statuses. See available documentation for this API endpoint

  1. Get the application ID for your integration. There are 2 ways:
    1. Retrieve the application ID from the JumpCloud Admin Portal:
      1. Log in to JumpCloud Admin Portal.
      2. Go to USER AUTHENTICATION > SSO.
      3. Open the Personio application by clicking on it.
      4. Note the ID from the URL which is just before “/details”: https://console.jumpcloud.com/#/sso/{222220da1f777fbe7502cde}/details
    2. Retrieve the application ID by making a GET /applications request:

curl command example:   

curl --request GET \

--url 'https://console.jumpcloud.com/api/applications?fields=id&filter=displayLabel:$eq:Personio' \

  --header 'x-api-key: REPLACE_KEY_VALUE' \

  --header 'x-org-id: REPLACE_ORG_ID_VALUE'

  1. To do a manual import, make a POST /applications/{application_id}/import/jobs request using the application ID from the preceding steps.

curl command example for importing new users and user updates with reactivation of users allowed:

curl --request POST \
--url 'https://console.jumpcloud.com/api/v2/applications/{application_id}/import/jobs' \
 --header 'accept: application/json' \
  --header 'Content-Type: application/json'\
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --header 'x-org-id: REPLACE_ORG_ID_VALUE'\

--data '{ 
      "allowUserReactivation": true, 
      "operations": [ 
    "users.create", 
         "users.update" 
    ]
  }'

curl command example for importing only user updates:

 curl --request POST \
--url 'https://console.jumpcloud.com/api/v2/applications/{application_id}/import/jobs'
 --header 'accept: application/json' \
  --header 'Content-Type: application/json'\
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --header 'x-org-id: REPLACE_ORG_ID_VALUE'\

--data '{
      "allowUserReactivation": true,
      "operations": [
         "users.update"
      ]
  }'

3. To run scheduled hourly imports:

curl command that allows reactivation, sends an advanced import filter, and sends the user import complete email after the hourly sync occurs:

curl --request POST \
  --url https://console.jumpcloud.com/api/v2/applications/{applicationObjectId}/import/schedules \
  --header 'content-type: application/json' \
  --data '{"allowUserReactivation":true,"operations":{"userCreate":true,"userUpdate":true},"query":"string","sendEmail":true}'

Updating the Personio Integration in JumpCloud

  1. Log in to JumpCloud Admin Portal.
  2. Go to USER AUTHENTICATION > SSO.
  3. Search for and select Personio from the list to reopen the configuration.
  4. Select the Identity Management tab.
  5. Change the desired values
  6. Click Update.

Troubleshooting

Issue: I’m getting an ‘Unable to fetch users’ error. 
Resolution: Your import timed out. Did you select all of the user attributes in the Readable employee attributes dropdown in Personio? Try selecting only the attributes you need versus all of the attributes and regenerating your credentials.

Issue: My import is taking a really long time and then it fails.
Resolution: You selected too many attributes with your credentials. Try selecting fewer attributes and regenerating your credentials.

Issue: I accidentally selected a user that I’ve already imported. Will it create a duplicate record?
Resolution: No, if the user has an email that already exists in JumpCloud, it will not create a duplicate record. 

Issue: Manager not being populated.
Resolution: If the manager doesn't exist in JumpCloud when the user was added or updated, the field will remain blank. Once the manager's user record is created in JumpCloud, the manager value will be added on the next update.

List IconIn this Article

Still Have Questions?

If you cannot find an answer to your question in our FAQ, you can always contact us.

Submit a Case