Skip to main content

Set Up SCIM With OneLogin

Jesse
  • 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

You need to be both an Admin in Lattice and in OneLogin to configure SCIM.

  1. Navigate to Admin > Organization > Account settings > API keys.
  2. Click Generate API Key.
  3. Copy the API Key to your clipboard.

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

  1. If you don't already have the Lattice app in your list of OneLogin apps, add it now.
  2. Open the Lattice app, and click on the Configuration tab.
  3. Enter your Lattice subdomain in the Lattice HQ Subdomain input field above. For example, if your organization's Lattice URL is https://bigco.latticehq.com, bigco would be your subdomain.
  4. Enter the API Key you created above into the SCIM Bearer Token input field.
  5. Leave SCIM JSON Template blank as it is not required.
  6. Click Enable in the API Connection section.
  7. Click Save.
  8. Go to the Provisioning tab on the left, and select Enable provisioning.

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.

Sync Custom Attributes to Lattice (Optional)

If you have custom fields that are specific to your company (For example shirt size, office location, etc.), you can set them up from OneLogin to Lattice automatically:

  1. Create a custom attribute in Lattice representing the field.
  2. Create the custom user field in OneLogin if it doesn't exist. 
  3. Map the OneLogin field to the Lattice field.

Map 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 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) > click Include in User Provisioning checkbox > click Save. Note: the Field name must not contain spaces.
  3. You should see another dropdown appear. Select the corresponding field from OneLogin you want to map, 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.

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

Additional Notes

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