Integrate with Rippling

Automatically provision, update and deprovision users in Rippling from JumpCloud using the Identity Management (SCIM) integration. Rippling customers have two options for integrating JumpCloud and Rippling:

1. A custom app in Rippling to create an integration with JumpCloud's SCIM API and get changes in real-time from Rippling.
2. JumpCloud's Identity Management Custom API connector to pull information from Rippling on a scheduled basis.

Leverage this integration to centralize user lifecycle and user identity in JumpCloud for Rippling. Save time and avoid mistakes, as well as potential security risks, related to manually creating users. Read this article to learn how to setup the Rippling integration.

Prerequisites

• A JumpCloud administrator account
• JumpCloud SSO Package or higher or SSO à la carte option
• The Rippling API Key package to obtain a customer API key
• A Rippling account with sufficient privileges and scopes to make API calls to the Rippling / endpoint
• Review the following documentation:
  • Rippling Customer Guide for using their API
  • Rippling Employees API documentation to determine which fields you want mapped

Considerations

• This integration only works with the Rippling API v1
• Rippling does not support SSO using an external Identity Provider
• Rippling has a pick list for certain fields, like employee type, so the values returned may not match the values that have been manually entered in those user fields in JumpCloud. If you have built dynamic group groups based on those user attributes, be sure to update your dynamic group rules to check for the values returned from Rippling in addition to or instead of the values that have been entered manually
• Input values are case sensitive

Creating a new custom application

To configure JumpCloud

1. Log in to the JumpCloud Admin Portal.
2. Navigate to USER AUTHENTICATION > SSO Applications.
3. Click + Add New Application.
4. Click Select in the Custom Application tile and then click Next.
5. Select Import Users from this app (Identity Management) and then click Next.
6. Enter Rippling for the Display Label. Optionally, you can enter a Description, adjust the User Portal Image and choose to hide or Show in User Portal.
7. Click Save Application.
8. If successful, click:
   • Configure Application and go to the next section.
   • Close to configure your new application at a later time.

To configure Rippling

Creating your Rippling API key

1. Log in to Rippling as an admin for your organization.
2. Select Company Settings.
3. Navigate to API Access.
4. Click Create API Key.
5. Provide the following scopes: 
   • employee:read
   • employee:name:read
   • employee:preferredFirstName:read
   • employee:preferredLastName:read
   • employee:employmentType:read
   • employee:workEmail:read
   • employee:title:read
   • employee:endDate:read
   • employee:employeeNumber:read
   • employee:department:read
   • employee:level:read
   • employee:userId:read
   • employee:manager:read
   • employee:teams:read
   • employee:workLocation:read
   • employee:workLocationId:read

6. Add a description for your API key.
7. Click Save.

Viewing your Rippling API keys

1. Log in to Rippling as an admin for your organization.
2. Select Company Settings.
3. Navigate to API Access.
4. You will then be able to copy or delete your API keys as desired.

Configuring the Custom API Integration

To configure JumpCloud

1. In JumpCloud, create a new application or select it from the Configured Applications list.
2. Select the Identity Management tab and enter or select the following information:
   • Service Provider Configuration
     • API Type - Custom API Import
     • Authentication method - Bearer Token
     • Base URL - https://api.rippling.com/platform/api 
     • Token Key - paste the Rippling API key generated above
   • Endpoint Configuration > List users > Location:
     • Resource Location - "." (the ”.” indicates the user array is the root)
     • Method - This field is not changeable and is always set to GET
     • Endpoint Path - /employees/include_terminated
   • Endpoint Configuration > List users > Total count:
     • Response Parameter Location - select Body
     • Response Body JSON Path - na (because the total count not being returned)
   • Endpoint Configuration > List users > Pagination:
     • Limit Name field - limit
     • Offset Name field - offset

3. Click Test Connection.
   • If successful - you will receive a success message and the fields for attribute mapping will appear
   • If unsuccessful - you will receive a failure notification that slides out from the right of the panel and the full error responses received from the service provider will be shown at the bottom of the Configuration Settings section
4. Click Activate.

User Schema Attribute Mapping

Once the connection and credentials have been tested and verified, the user schema mapping section will open. There are recommended and optional mappings.

1. Enter the following information:
   • Unique ID - id
   • User Status - roleState
   • Inactive Status Values - TERMINATED
2. In the Service provider attribute JSON path column, complete the two required field mappings by entering the following value:
   • Company email - workEmail
   • Username - workEmail 
3. Click Preview to see the Rippling employee schema and how the mappings will be applied in JumpCloud. 

4. Click ok to close the User schema preview window.
5. Complete the optional mappings:

• First Name - firstName 
• Last Name - lastName 
• Employee Type - employmentType
• Job Title - title 
• Department - department 
• Work City - workLocation.city 
• Work Street Address - workLocation.streetLine1 
• Work Postal Code - workLocation.zip 
• Work Country - workLocation.country
•  Work State - workLocation.state
• Employee Identifier - id 

6. Click Preview again to verify the mappings.
7. Click ok to close the User schema preview window.
8. Click Activate.
9. If successful, you will receive a message saying the Identity Management integration has been successfully verified.
10. Click save.

Importing New Users from JumpCloud Admin Portal

1. Log in to the JumpCloud Admin Portal.
2. Go to USER AUTHENTICATION > SSO and open the Rippling application by clicking on it from the list.
3. Select the Identity Management tab.
4. Click manual import.
5. Select the users you want to import:
   • You can filter the list further to only show users who do not exist in your JumpCloud organization by clicking the checkbox next to Show NEW users only
   • The count of users to be imported will show at the bottom left hand of the list
6. Click import.
   • If there are 100 users or less being imported, the results will be shown in real-time and emailed to the email address associated with your JumpCloud account. 
   • If more than 100 users are being imported, the import will be done in the background. You will receive an email informing you that the import is complete.
7. You can navigate to the Users page, User Groups page, or Device Groups page by clicking on the links in the cards above the results, or close the window.

Importing user updates

To import user updates from the JumpCloud API

1. Retrieve the application ID for your configured integration using one of the below options:
   • JumpCloud Admin Portal:
     • Log in to the JumpCloud Admin Portal.
     • Go to USER AUTHENTICATION > SSO Applications and open the Rippling application by clicking on it from the list.
     • Note the id from the URL which is just before “/details”: https://console.jumpcloud.com/#/sso/222220da1f777fbe7502cde/details
     • JumpCloud API:
       • Create a GET /applications request:

curl command example:

2. Make a POST /applications/{application_id}/import/jobs request using the application id from the preceding steps.

curl command example:

API reference

3. If the import request is successful, you will receive a success response that includes a JSON object with the import job id. 
4. When the import is complete, you will receive an email.

To import user updates from the JumpCloud Admin Portal

1. Log in to the JumpCloud Admin Portal.
2. Go to USER AUTHENTICATION > SSO Applications and open the Rippling application by clicking on it from the list.
3. Select the Identity Management tab.
4. Optionally, check the box for Allow reactivation of users on update if you want to allow a user to be reactivated in JumpCloud if their roleState changes from TERMINATED to ACTIVE in Rippling.
5. Click Start Import.
6. Select the import you would like to do perform.

7. If you select Import new users and user updates, Only import new users, or Only import new users option, a job will be submitted that will run in the background.
8. If you select View and select specific users to import, you will be able to select the specific users you want to import and update.

9. Select the users to import and update.
10. Click Import.
11. You will be shown the job information and provided options for next steps you can take for user and authorization management.
12. When the import is complete, you will receive an email.

Updating the Custom API Connector

1. Log in to the JumpCloud Admin Portal.
2. Go to USER AUTHENTICATION > SSO Applications and open the Rippling application by clicking on it from the list.
3. Select the Identity Management tab.
4. Make the desired changes in the Configuration Settings section.
5. Click update.

Removing the Integration

To deactivate the IdM 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 on the left hand panel, click the Deactivate IdM connection link.
5. Click confirm. 
6. If successful, you will receive a confirmation message.

To deactivate the SSO Integration or Bookmark

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. Select the SSO or Bookmark tab.
5. Scroll to the bottom of the configuration.
6. Click Deactivate SSO or Deactivate Bookmark. 
7. Click save. 
8. If successful, you will receive a confirmation message.

To delete the application

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 delete.
4. Check the box next to the application to select it.
5. Click Delete.
6. Enter the number of the applications you are deleting
7. Click Delete Application.
8. If successful, you will see an application deletion confirmation notification.