Import Users with a Custom API Integration

Seamlessly onboard new users and sync user updates from your organization’s user identity source of truth - applications such as HRIS, HCM, compensation, and benefits solutions. Create efficiencies for IT and HR by reducing manual overhead and security concerns related to manual data entry and access based on outdated user data.

If you do not see an integration available in the list of HR Directories, Cloud Directories, or application integrations in the Admin Portal, you may be able to create an integration using a custom API integration. Read this article to learn how to configure a custom API integration.

Prerequisites

• An account with sufficient privileges and scopes to make API calls to the application and to the specific endpoints that will be used for the integration
• Detailed REST API documentation for the application that includes the information needed to complete the configuration
• Verification that the application API meets the following requirements:
  • Supports API Key, Bearer Token, or OAuth 2.0 authorization code as the authentication method
  • Supports offset pagination (limit/offset)
  • Accepts JSON requests and returns JSON responses
  • Has an endpoint that lists all the employees or users and returns the full schema (not a list of ids or a single value)

Considerations

• An SSO configuration is recommended, not required
• Although a custom API option is provided on all applications that do not have a pre-built identity management integration for convenience, this should not be interpreted as a validation that the application has a REST API or that an integration can be successfully configured
• An integration cannot be created for any application with a custom REST API that:
  • Requires multiple custom headers
  • Does not return the full schema for the list users endpoint (e.g., only ids are returned)
  • Returns responses in any format other than JSON
  • Requires the following authentication methods: OAuth 2.0 basic auth header, client credentials, refresh token, or authorization code with PKCE
• Partial configurations are not saved even if the application is saved
• The timestamp in the User Import Complete email is UTC
• See Troubleshoot: Custom API Integrations for a list of HRIS solutions for which a custom API integration cannot currently be used to create an integration

Creating a New Application Connector

1. Log in to the JumpCloud Admin Portal.
2. Navigate to USER AUTHENTICATION > SSO Applications.
3. Enter the application name in the Search field:
   • Search for the application in the catalog, and select it.
4. If the application does not exist in the catalog:
   • Click + Add New Application, select Custom Application and click Next.
5. Select one of the following and click Next:
   • Import Users from this app (Identity Management).
   • Export users to this app (Identity Management).
   • Add a bookmark (no SSO)
6. Enter a Display Label.
7. Enter a Description (optional).
8. Choose a Display Option (optional).
9. If this is a bookmark application, enter the URL in the Bookmark URL field.
10. Select whether to hide or Show in User Portal.
11. Click Save Application.
12. To continue setting up the application, click Configure Application.

Configuring the Custom API Identity Management Integration

1. Create a new application or select it from the Configured Applications list.
2. Select the Identity Management tab.
3. Under Configuration settings > Service Provider Configuration > API Type, choose Custom API Import.
4. Optionally, if you want to use a method for mutual authentication, check Use mTLS authentication under Mutual TLS (mTLS). Add the following required files:
   • Private Key – click Choose File and then browse to and select the private key file
   • Certificate – click Choose File and then browse to and select the certificate file
5. Select the appropriate Authentication Method:
   • Bearer Token
   • API Key
   • OAuth 2.0

Authentication Method Configuration

Bearer Token

1. Enter the Base URL.

2. Follow the Service Provider’s (SP’s) instructions for generating the token.
3. Enter the token in the Token Key field.

API Key

1. Follow the SP’s instructions for generating the API Key.
2. Enter the following information:
   • Base URL
   • Header name.
   • Header value (which will include the API Key)

3. Optionally, click + Add Header to add an additional Header.
4. Enter the following information:
   • Header name.
   • Header value (which will include the API Key)

OAuth 2.0

1. Follow the SP’s instructions for generating the Client ID and Client Secret.
2. Under Grant Type, there are two choices available:
   • Authorization Code
   • Client Credentials

Authorization Code

1. Enter values in the following required fields:
   • Client ID
   • Client Secret
   • Authorization URL
   • Access Token URL
2. If needed, enter values in optional fields:
   • Revoke URL
   • Scopes

3. If successful, you will be redirected to the SP’s page. Click Authorize.
4. You will be redirected back to the Identity Management tab in your Admin Portal.

Client Credentials

1. Enter values in the following required fields:
   • Client ID
   • Client Secret
   • Access Token URL
2. If needed, enter a value in the optional Scopes field.

3. If successful, you will be redirected to the SP’s page. Click Authorize.
4. You will be redirected back to the Identity Management tab in your Admin Portal.

Endpoint Configuration

Fill out the required fields specific to your configuration.

1. Base URL – Enter the SP’s Base URL.
2. List Users:
   • Location:
     • Resource Location – Enter the JSON path for the location of the user or employee object in the API response.
       • If the user array is the root, then the path is “.”.
       • If the user array is a field in the root “fieldname”. Example: users
       • If it’s a nested field “fieldA.fieldB…fieldname”. Example: data.resources.users
     • Method – This field is greyed out (not changeable) and is always set to GET.
     • Endpoint Path – Enter the relative URL used to request the entire list of users from the application in the field.

3. Total count:
   • Response Parameter Location – Select the appropriate value from the dropdown.
     Note: Review the REST API documentation to determine if the total number of records returned by the API request, often referred to as total count, is included in the header or the body of the response and what the header name or JSON path, respectively, is for that value.
   • If the total count value is returned in the body, enter the json path for the property in in the Response Body JSON Path field. Example: meta.total_count. 
   • If the total count is returned in the header, enter the header name where the total count will be returned in the Response Header Name field. Example: X-Total-Count.
     Note: If the total number of records is not returned by the SP, then you can enter a value such as “na”.
4. Pagination:
   • Limit Name – Enter the parameter name used to control how many results are returned per request from the List endpoint in the field. Common names for this parameter include limit, per_page.
   • Offset Name – Enter the parameter name used to specify on which result to start in the total number of returned results field. Common names for this parameter include offset, skip.
5. For API Key and Bearer Token Configurations, select Test Connection.
   • If successful – you will receive a success message and the fields for attribute mapping will appear.
   • unsuccessful – you will receive a failure notification that slides out from the right of the panel and the full error responses received from the SP will be shown at the bottom of the Configuration Settings section.

User Schema Attribute Mapping

1. Complete the 2 required mapping fields:
   • Company email
   • Username

2. Complete the optional mappings.

3. Click Preview to see how the mappings will be applied in JumpCloud.

4. Click ok to close the User schema preview window.
5. Click Activate.
6. If successful, you will receive a message saying the Identity Management integration has been successfully verified.
7. Click save.

Importing New Users and Updates

To import users with the JumpCloud Admin Portal

1. Create a new application or select it from the Configured Applications list.
2. Select the Identity Management tab.
   
3. There are several settings available for importing users from your custom application to JumpCloud. Warning: Selected import options will apply to both manual and scheduled imports. 
   • Expand the Import Users section.
     • Manual Import – clicking the Start Manual Import button kicks off the process flow for doing an immediate and one-time import of users from your custom application to JumpCloud. 
     • 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.
     • 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. 
   • In the Import Settings section, you can optionally choose:
     • Allow reactivation of users on update. Checking 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 your custom application.  
     • Apply Advanced Filters on import (optional). See your custom application’s API documentation for available filters.

To start a manual user import

1. Expand the Import Users section and click Start Manual Import.
2. Select one of the following options: 
   • Import new users and user updates
   • Only import new users
   • Only import user updates
   • View and select specific new users to import (updates not supported)

3. Click Continue.
4. If you selected the View and select specific new users to import (updates not supported).
   • Select the users you want to import.

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

8. 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.
9. You can now connect users to all their JumpCloud resources. Learn more in the Authorize Users to an SSO App and Connect New Users to Resources articles.

To import users with the JumpCloud API

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

curl command example:   

2. 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 command example for importing only user updates:

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:

Updating a Custom API Connector

1. Log in to the JumpCloud Admin Portal.
2. Navigate to USER AUTHENTICATION > SSO Applications.
3. Open the application by clicking on it.
4. Select the Identity Management tab.
5. Make the desired changes in the Configuration Settings section.

6. Click update.

Deactivating the Custom API Integration

1. Log in to the JumpCloud Admin Portal.
2. Go to USER AUTHENTICATION > SSO Applications.
3. Search for the application that you’d like to deactivate and click to open its details panel. 
4. Under the company name and logo of the left hand panel at the very bottom, click the Deactivate IdM connection link.
5. Click confirm to deactivate Identity Management for the application.