- \n
- 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 <\/li>\n\n\n\n
- Detailed REST API documentation for the application that includes the information needed to complete the configuration<\/li>\n\n\n\n
- Verification that the application API meets the following requirements:\n
- \n
- Supports API Key, Bearer Token, or OAuth 2.0 authorization code as the authentication method<\/li>\n\n\n\n
- Supports offset pagination (limit\/offset)<\/li>\n\n\n\n
- Accepts JSON requests and returns JSON responses<\/li>\n\n\n\n
- Has an endpoint that lists all the employees or users and returns the full schema (not a list of ids or a single value)<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n
![](\"\/wp-content\/themes\/jumpcloud\/assets\/images\/gutenberg-blocks\/important-icon.png\")
<\/p><\/div>Important:<\/strong> \nThis feature is a generic\/custom option that has a high likelihood of allowing you to create an integration with applications that meet the requirements noted above, but there may be situations where this option cannot be used.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
Considerations<\/strong><\/p>\n\n\n\n
- \n
- An SSO configuration is recommended, not required<\/li>\n\n\n\n
- 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<\/li>\n\n\n\n
- An integration cannot be created for any application with a custom REST API that:\n
- \n
- Requires multiple custom headers<\/li>\n\n\n\n
- Does not return the full schema for the list users endpoint (e.g., only ids are returned)<\/li>\n\n\n\n
- Returns responses in any format other than JSON<\/li>\n\n\n\n
- Requires the following authentication methods: OAuth 2.0 basic auth header, client credentials, refresh token, or authorization code with PKCE<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Partial configurations are not saved even if the application is saved<\/li>\n\n\n\n
- The timestamp in the User Import Complete<\/strong> email is UTC<\/li>\n\n\n\n
- See Troubleshoot: Custom API Integrations<\/a> for a list of HRIS solutions<\/mark> for which a custom API integration cannot currently be used to create an integration<\/li>\n<\/ul>\n\n\n\n
Creating a New Application Connector<\/strong><\/h2>\n\n\n\n
![](\"\/wp-content\/themes\/jumpcloud\/assets\/images\/gutenberg-blocks\/note-icon.png\")
<\/p><\/div>Note:<\/strong> \nSkip to the next section if you have already configured the application connector.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- Log in to the JumpCloud Admin Portal<\/a>.<\/li>\n\n\n\n
- Navigate to USER AUTHENTICATION > SSO<\/strong> Applications<\/strong>.<\/li>\n\n\n\n
- Enter the application name in the Search field:\n
- \n\n
- Search for the application in the catalog, and select it.<\/li>\n\n<\/ul>\n<\/li>\n\n\n\n
- If the application does not exist in the catalog:\n
- \n
- Click + Add New Application<\/strong>, select Custom Application<\/strong> and click Next<\/strong>.<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Select one of the following and click Next<\/strong>:\n
- \n
- Import Users from this app (Identity Management).<\/li>\n\n\n\n
- Export users to this app (Identity Management).<\/li>\n\n\n\n
- Add a bookmark (no SSO)<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Enter a Display Label<\/strong>.<\/li>\n\n\n\n
- Enter a Description<\/strong> (optional).<\/li>\n\n\n\n
- Choose a Display Option <\/strong>(optional).<\/li>\n\n\n\n
- If this is a bookmark application, enter the URL in the Bookmark URL<\/strong> field.<\/li>\n\n\n\n
- Select whether to hide or Show in User Portal<\/strong>.<\/li>\n\n\n\n
- Click Save Application<\/strong>.<\/li>\n\n\n\n
- To continue setting up the application, click Configure Application<\/strong>.<\/li>\n<\/ol>\n\n\n\n
Configuring the Custom API <\/strong>Identity Management Integration<\/strong><\/h2>\n\n\n\n
- \n
- Create a new application<\/a> or select it from the Configured Application<\/strong>s list.<\/li>\n\n\n\n
- Select the Identity Management<\/strong> tab.<\/li>\n\n\n\n
- Under Configuration settings > Service Provider Configuration > API Type<\/strong>, choose Custom API<\/strong> Import<\/strong>.<\/li>\n\n\n\n
- Optionally, if you want to use a method for mutual authentication, check Use mTLS authentication<\/strong> under Mutual TLS (mTLS)<\/strong>. Add the following re<\/mark>quired files:\n
- \n
- Private Key<\/strong> – click Choose File<\/strong> and then browse to and select the private key file<\/li>\n\n\n\n
- Certificate<\/strong> – click Choose File<\/strong> and then browse to and select the certificate file<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Select the appropriate Authentication Method:\n
- \n\n
- Bearer Token<\/a><\/li>\n\n\n
- API Key<\/a><\/li>\n\n\n
- OAuth 2.0<\/a><\/li>\n\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
Authentication Method Configuration<\/strong><\/h3>\n\n\n\n
Bearer Token<\/strong><\/h4>\n\n\n\n
- \n
- Enter the Base URL<\/strong>.<\/li>\n<\/ol>\n\n\n\n
![](\"\/wp-content\/themes\/jumpcloud\/assets\/images\/gutenberg-blocks\/tip-icon.png\")
<\/p><\/div>Tip:<\/strong> \nThis information will be located in the REST API documentation for the application.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- Follow the Service Provider’s (SP\u2019s) instructions for generating the token.<\/li>\n\n\n\n
- Enter the token in the Token Key<\/strong> field.<\/li>\n<\/ol>\n\n\n\n
API Key<\/strong><\/h4>\n\n\n\n
- \n
- Follow the SP\u2019s instructions for generating the API Key.<\/li>\n\n\n\n
- Enter the following information:\n
- \n
- Base URL<\/strong><\/li>\n\n\n\n
- Header name<\/strong>.<\/li>\n\n\n\n
- Header value<\/strong> (which will include the API Key)<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
<\/p><\/div>Tip:<\/strong> \nThe Header name<\/strong>, the format for the Header value<\/strong>, and Base URL<\/strong> will be located in the REST API documentation for the application.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- Optionally, click + Add Header<\/strong> to add an additional Header.<\/li>\n\n\n\n
- Enter the following information:\n
- \n
- Header name<\/strong>.<\/li>\n\n\n\n
- Header value<\/strong> (which will include the API Key)<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
OAuth 2.0<\/strong><\/h4>\n\n\n\n
- \n
- Follow the SP\u2019s instructions for generating the Client ID and Client Secret.<\/li>\n\n\n\n
- Under Grant Type<\/strong>, there are two choices available:\n
- \n
- Authorization Code<\/a><\/li>\n\n\n\n
- Client Credentials<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
Authorization Code<\/h5>\n\n\n\n
- \n
- Enter values in the following required fields:\n
- \n\n
- Client ID<\/strong><\/li>\n\n\n
- Client Secret<\/strong><\/li>\n\n\n
- Authorization URL<\/strong><\/li>\n\n\n
- Access Token URL<\/strong><\/li>\n\n<\/ul>\n<\/li>\n\n\n\n
- If needed, enter values in optional fields:\n
- \n\n
- Revoke URL<\/strong><\/li>\n\n\n
- Scopes<\/strong><\/li>\n\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
<\/p><\/div>Tip:<\/strong> \nIf multiple scopes need to be specified, separate each scope with a space.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- If successful, you will be redirected to the SP\u2019s page. Click Authorize<\/strong>.<\/li>\n\n\n\n
- You will be redirected back to the Identity Management<\/strong> tab in your Admin Portal.<\/li>\n<\/ol>\n\n\n\n
Client Credentials<\/h5>\n\n\n\n
- \n
- Enter values in the following required fields:\n
- \n
- Client ID<\/strong><\/li>\n\n\n\n
- Client Secret<\/strong><\/li>\n\n\n\n
- Access Token URL<\/strong><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- If needed, enter a value in the optional Scopes <\/strong>field.<\/li>\n<\/ol>\n\n\n\n
<\/p><\/div>Tip:<\/strong> \nIf multiple scopes need to be specified, separate each scope with a space.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- If successful, you will be redirected to the SP\u2019s page. Click Authorize<\/strong>.<\/li>\n\n\n\n
- You will be redirected back to the Identity Management<\/strong> tab in your Admin Portal.<\/li>\n<\/ol>\n\n\n\n
Endpoint Configuration<\/strong><\/h3>\n\n\n\n
Fill out the required fields specific to your configuration.<\/p>\n\n\n\n
<\/p><\/div>Tip:<\/strong> \nThis information will be located in the REST API documentation for the application.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- Base URL –<\/strong> Enter the SP\u2019s Base URL.<\/li>\n\n\n\n
- List Users<\/strong>:\n
- \n\n
- Location<\/strong>:\n\n
- \n\n
- Resource Location<\/strong> – Enter the JSON path for the location of the user or employee object in the API response.\n\n
- \n\n
- If the user array is the root, then the path is “.”.<\/li>\n\n\n
- If the user array is a field in the root “fieldname”. Example: users<\/li>\n\n\n
- If it’s a nested field “fieldA.fieldB…fieldname”. Example: data.resources.users<\/li>\n\n<\/ul>\n\n<\/li>\n\n\n
- Method <\/strong>– This field is greyed out (not changeable) and is always set to GET.<\/li>\n\n\n
- Endpoint Path <\/strong>– Enter the relative URL used to request the entire list of users from the application in the field.<\/li>\n\n<\/ul>\n\n<\/li>\n\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
<\/p><\/div>Note:<\/strong> \nThis value will be appended to the Base URL. Common examples include: \/profiles, \/employees, or \/users.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
- \n
- Total count<\/strong>:\n
- \n\n
- Response Parameter Location – Select the appropriate value from the dropdown.
Note<\/strong>: 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 <\/strong>or the body <\/strong>of the response and what the header name or JSON path, respectively, is for that value.<\/li>\n\n\n- If the total count value is returned in the body<\/strong>, enter the json path for the property in in the Response Body JSON Path field<\/strong>. Example<\/strong>: meta.total_count. <\/li>\n\n\n
- If the total count is returned in the header<\/strong>, enter the header name where the total count will be returned in the Response Header Name<\/strong> field. Example<\/strong>: X-Total-Count.
Note<\/strong>: If the total number of records is not returned by the SP, then you can enter a value such as \u201cna\u201d.<\/li>\n\n<\/ul>\n<\/li>\n\n\n\n- Pagination:<\/strong>\n
- \n\n
- Limit Name<\/strong> – 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.<\/li>\n\n\n
- If the total count value is returned in the body<\/strong>, enter the json path for the property in in the Response Body JSON Path field<\/strong>. Example<\/strong>: meta.total_count. <\/li>\n\n\n
- Response Parameter Location – Select the appropriate value from the dropdown.
- Endpoint Path <\/strong>– Enter the relative URL used to request the entire list of users from the application in the field.<\/li>\n\n<\/ul>\n\n<\/li>\n\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
- Resource Location<\/strong> – Enter the JSON path for the location of the user or employee object in the API response.\n\n
- List Users<\/strong>:\n
- You will be redirected back to the Identity Management<\/strong> tab in your Admin Portal.<\/li>\n<\/ol>\n\n\n\n
- Client Secret<\/strong><\/li>\n\n\n\n
- Client ID<\/strong><\/li>\n\n\n\n
- You will be redirected back to the Identity Management<\/strong> tab in your Admin Portal.<\/li>\n<\/ol>\n\n\n\n
- Scopes<\/strong><\/li>\n\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
- Client Secret<\/strong><\/li>\n\n\n
- Client ID<\/strong><\/li>\n\n\n
- Client Credentials<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
- Authorization Code<\/a><\/li>\n\n\n\n
- Header value<\/strong> (which will include the API Key)<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
- Enter the following information:\n
- Header name<\/strong>.<\/li>\n\n\n\n
- Base URL<\/strong><\/li>\n\n\n\n
- API Key<\/a><\/li>\n\n\n
- Certificate<\/strong> – click Choose File<\/strong> and then browse to and select the certificate file<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Select the Identity Management<\/strong> tab.<\/li>\n\n\n\n
- Enter a Description<\/strong> (optional).<\/li>\n\n\n\n
- Select one of the following and click Next<\/strong>:\n
- Click + Add New Application<\/strong>, select Custom Application<\/strong> and click Next<\/strong>.<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Navigate to USER AUTHENTICATION > SSO<\/strong> Applications<\/strong>.<\/li>\n\n\n\n
- See Troubleshoot: Custom API Integrations<\/a> for a list of HRIS solutions<\/mark> for which a custom API integration cannot currently be used to create an integration<\/li>\n<\/ul>\n\n\n\n