Skip to main content

Set Up SCIM With OneLogin

Jesse Charvat
  • Updated

How to set up your SCIM in Lattice

Lattice allows you to automatically configure OneLogin to send user profile updates to Lattice using SCIM. The supported features include:

  1. Create Users: When a user is created or activated in OneLogin, they will automatically be created or reactivated in Lattice.
  2. Update User Attributes: When a user attribute is changed in OneLogin, the corresponding user profile in Lattice will automatically be updated.
  3. Deactivate Users: When a user is deactivated or disabled in OneLogin, the corresponding user in Lattice will automatically be deactivated.

Configure SCIM in Lattice

Note: an API key can give a server access to almost all of your Lattice data! Treat this key as if it were your password — do not share this key with anyone you do not trust, and avoid sending it to others over IM or email.

  1. Navigate to Admin > Organization > Settings > API keys.
  2. Click Generate API Key.
  3. Copy the API Key to your clipboard.
Untitled.png

Ensure you copy the exact value of this key (including all of the dashes) and store it somewhere secure. We'll need this key in the next step when configuring SCIM in OneLogin.

Note: if you revoke this API key, then the SCIM integration will not work. If you believe your key has been compromised, create a new key, update your OneLogin settings, then revoke the old key.

Configure SCIM in OneLogin

If you are not an admin in OneLogin, please get your company's admin and have them complete the following steps.

  1. If you don't already have the Lattice app in your list of OneLogin apps, add it now.
  2. Select the Lattice app, and click on the Configuration tab. You should see the following form:
  3. Enter your Lattice subdomain in the Lattice HQ Subdomain input field above. (Note: the subdomain is the bolded portion of your Lattice URL: https://yourcompany.latticehq.com)
  4. Leave SCIM JSON Template blank as it is not required.
  5. Enter the API Key you created above into the SCIM Bearer Token input field.
  6. Click Enable in the API Connection section.
  7. Click Save at the top of the page.
  8. Go to the Provisioning tab on the left, and ensure that Enable provisioning is selected:Note: if you check the boxes under "Require admin approval before this action is performed," then you will have to approve every user provisioning event manually. Leave these boxes unchecked if you wish to keep this automated.
  9. The settings should match what you see in the above form. Once you are satisfied with the settings, click Save.

If you've made it this far, great job! You're done. The next section is completely optional and only necessary if you have special custom fields in OneLogin that you would like to sync to Lattice.

Optional: Syncing Custom Attributes to Lattice

You may have custom fields that are specific to your company, for example, "shirt size" (or more commonly, "office location," "job level," and "salary band"). These fields can easily be set up to sync from OneLogin to Lattice automatically. Syncing custom attributes to Lattice consists of three main steps:

  1. Create a "custom attribute" in Lattice representing the field.
  2. Create the "custom user field" in OneLogin if it doesn't exist. Populating this field is up to you!
  3. Map the OneLogin field to the Lattice field so the integration knows what to update.

If you are unsure how to create a custom attribute in Lattice, please refer to this article.

Mapping OneLogin Custom Fields to Lattice Custom Attributes

Once the fields are created, all that's left is to map them so that they can be sent over the SCIM integration.

  1. Navigate to the Parameters tab, scroll down to the Optional Parameters section, and click the + icon in the upper right.Note: for fields like "Phone Number" to sync, you must enable them manually as they are disabled by default.
  2. Enter a name for the mapping without spaces (e.g., "myShirtSize"), toggle the checkbox on for user provisioning, then click Save. We will need this name later!Note: the "Field name" must not contain spaces.
  3. You should see another dropdown appear. Select the corresponding field you created in OneLogin, then click Save again.
  4. Now, the mapping is created and all that's left to do is update the SCIM JSON template. Go to the Configuration tab and scroll down to the SCIM JSON template textbox. If you have not already, please enter the following JSON:
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
  "urn:ietf:params:scim:schemas:extension:lattice:attributes:1.0:User"
  ],
  "externalId": "{$user.id}",
  "userName": "{$parameters.email}",
  "name": {
    "familyName": "{$user.lastname}",
    "givenName": "{$user.firstname}",
    "formatted": "{$user.display_name}"
  },
  "phoneNumbers": [{
    "value": "{$parameters.phoneNumber}",
    "type": "work"
  }],
  "emails": [{
    "value": "{$user.email}",
    "type": "work",
    "primary": true
  }],
  "title": "{$parameters.title}",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "{$parameters.department}",
    "manager": {
      "value": "{$parameters.external_manager_id}",
      "displayName": "{$user.manager_firstname} {$user.manager_lastname}"
    }
  },
  "urn:ietf:params:scim:schemas:extension:lattice:attributes:1.0:User": {
    "startDate": "{$parameters.startDate}",
    "birthDate": "{$parameters.birthDate}",
    "gender": "{$parameters.gender}"
  }
}

Below the gender field, add another line for the attributes we just created. In this example, "My Shirt Size Lattice Attr" is the exact name of the custom attribute in Lattice, and "myShirtSize" is the name of the field mapping we created in step 2 above:

{
  ...
  "urn:ietf:params:scim:schemas:extension:lattice:attributes:1.0:User": {
    ...
    "gender": "{$parameters.gender}",
    "My Shirt Shize Lattice Attr": "{$parameters.myShirtSize}"
  }
}

 

Note: valid JSON does not contain trailing commas, so you would not add a comma after this line if it is the last line.

Click Save in the upper right corner, and your custom field should now sync from OneLogin to Lattice. 

All done!

Well done! You have successfully configured OneLogin to provision users into Lattice. Note that you must assign your users to the Lattice SCIM app; otherwise, OneLogin won't know which users it should provision into Lattice. This can be done with OneLogin's Roles and Groups.

Additional Notes

Lattice does not support case-sensitive emails. Please ensure that your users' emails are case-insensitive. That is, two users cannot share emails that only differ by character casing, e.g., "ALICE@yourcompany.com" is treated as being equal to "alice@yourcompany.com".

Related articles