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
  1. Add a description for your API key.
  2. Click Save.

Warning:

If you do not click activate before entering data in the Identity Management tab, you will lose any data you entered that tab.

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

Note:

The Rippling API documentation does not reference total count, so this information is likely not returned. The values entered will be ignored. 

  1. Endpoint Configuration > List users > Pagination:
    • Limit Name field – Enter limit.
    • Offset Name field – Enter offset.
  2. 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. 

Tip:

You can drag the bottom right corner of each section to see the entire schema. You can copy the contents into a text editor to copy and paste attributes.

  1. Click ok to close the User schema preview window.
  2. Complete the optional mappings:

Tip:

It is highly recommended to map the attributes marked as suggested, which are the attributes shown in the Optional mappings section by default. The dropdown shows all other user attributes that can be mapped to create a complete user profile.

  • 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
  1. Click Preview again to verify the mappings.
  2. Click ok to close the User schema preview window.
  3. Click Activate.
  4. If successful, you will receive a message saying the Identity Management integration has been successfully verified.
  5. 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.
  1. Click import.
  2. 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. 
  3. 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.
  4. 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:

curl --request GET \
--url
'https://console.jumpcloud.com/api/applications?fields=id&filter=displayLabel:$eq:Rippling' \
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --header 'x-org-id: REPLACE_ORG_ID_VALUE'

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

curl command example:


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'\
  --d '{
      "allowUserReactivation": true,
      "operations": [
         "users.create",
         "users.update"
      ]
  }

API reference

  1. If the import request is successful, you will receive a success response that includes a JSON object with the import job id. 
  2. 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.

Note:

Users with a roleState of TERMINATED will not be created 

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

Note:

Users with an Import Status of “New” do not exist in JumpCloud. Users with an Import Status of “Imported” already exist in JumpCloud.

  1. Select the users to import and update.
  2. Click Import.
  3. You will be shown the job information and provided options for next steps you can take for user and authorization management.
  4. 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

Important:

These are steps for removing the integration in JumpCloud. Consult your SP's documentation for any additional steps needed to remove the integration in the SP. Failure to remove the integration successfully for both the SP and JumpCloud may result in users losing access to the application.

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.

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