Integrate with Rippling

Import users from Rippling using the JumpCloud open integration option - the Identity Management Custom API connector. Read this article to learn how to setup the Rippling integration.

Prerequisites

• A JumpCloud administrator account.
• JumpCloud SSO Package or higher or SSO add-on feature.
• 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 Rippling Customer Guide for using their API.
• Review the Rippling Employees API documentation to determine which fields you want mapped.

Considerations

• Rippling does not support SSO using an external Identity Provider.

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.
3. Configuration settings > Service Provider Configuration
   • API Type – Custom API.
   • Authentication method – Bearer Token.
   • Base URL – enter https://api.rippling.com/platform/api 
   • Token Key – paste the Rippling API key generated above. 
4. Endpoint Configuration > List users > Location:
   • Resource Location – Enter “.” (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
5. Endpoint Configuration > List users > Total count:
   • Response Parameter Location – select body.
   • Response Body JSON Path Enter “na” because the total count not being returned.

3. Endpoint Configuration > List users > Pagination:
   • Limit Name field – Enter limit.
   • Offset Name field – Enter offset.
4. Scroll back up to the top of the Configuration settings section and 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.

User Schema Attribute Mapping

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

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

6. Click ok to close the User schema preview window.
7. Complete the optional mappings:

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

8. Click Preview again to verify the mappings.
9. Click ok to close the User schema preview window.
10. Click Activate.
11. If successful, you will receive a message saying the Identity Management integration has been successfully verified.
12. 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.
7. 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. 
8. 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.
9. 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:
   1. 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. Note the id from the URL which is just before “/details”: https://console.jumpcloud.com/#/sso/222220da1f777fbe7502cde/details
   2. JumpCloud API:
      1. 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

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 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.