Skip to main content

Okta SCIM - Initial Setup Guide

Setup SCIM via Okta with a Custom App Integration

Updated yesterday

Overview

This guide is intended to help IT Administrators setup SCIM provisioning for Reclaim.ai via Okta.

Note: SCIM is currently only available for authentication to users with primary calendars from Google; SCIM is not yet available for Microsoft O365 calendars, but we are tracking/working on this.

This is for creating a new "Custom App" while the Reclaim.ai App in the Okta App Catalog is under review.

If you need any additional assistance beyond this guide, please reach your to your Reclaim.ai contact/rep, or support via our website and/or [email protected].

Pre-Requirements

  1. Setup on a Reclaim.ai Enterprise Plan (see: https://reclaim.ai/pricing) or a Business Trial

  2. Have your domain enabled/configured for SSO in Reclaim.ai

  3. Have a "Auto Capture" enabled on your Reclaim Team (if you are unsure if this is the case, ask your contact/rep and/or [email protected]).

  4. Have a Google Service Account setup and enabled (see: https://help.reclaim.ai/en/articles/6520530-using-google-workspace-service-accounts-to-roll-out-reclaim-to-your-enterprise)

  5. Have an "Admin" Role on your Reclaim Team - You can check the Team Billing Page (https://app.reclaim.ai/billing) for your Team to verify this.

  6. Administrator access to your Okta Account/Dashboard

For 1-4: Work with your Reclaim.ai contact/rep or reach out to [email protected] if you are unsure.

Create an API Key in Reclaim.ai

  1. Login to Reclaim.ai (https://app.reclaim.ai/login)

  2. In your URL bar enter: https://app.reclaim.ai/settings/developer

  3. Generate a new API Key:

    1. Enter a Name for the key, such as "Okta SCIM"

    2. Set Expiration to "Never" (or whatever is appropriate for your security policy)

    3. Click "Generate key"

    4. Click the "Copy" icon to copy the key to your clipboard

    5. Save the key some place secure for future use

Now you can continue on with the Okta portion of the setup.

Create a new App Integration in Okta for SCIM

This step will create a new custom application integration for SCIM for Reclaim.ai in Okta. This is in addition to the ODIC App you created for SSO.

The current Reclaim.ai App in the Okta App Catalog is currently only for SSO; an updated version including SCIM support has submitted to Okta for approval in their App Catalog, and this guide will be updated when that is complete. For now, follow the steps below to setup Reclaim.ai as a custom Application Integration specifically for SCIM.

  1. Login to Okta as an Admin

  2. From the Left nav goto: Applications->Applications

  3. From the Applications screen, click “Browse App Catalog”:

  4. From the “Browse App Catalog” screen:

    1. Type in "SCIM" and select "SCIM 2.0 Test App (Header Auth)"

    2. Click the "Create New App" button

  5. From the “SCIM 2.0 Test App (Header Auth)” screen click the "Add Integration" button:

  6. On the "SCIM 2.0 Test App (Header Auth)" page:

    1. For "Application label" enter "Reclaim.ai SCIM" (or something similar of your choosing).

    2. Make sure box check boxes are unchecked

    3. Click the “Next” button

  7. On the "Sign-On Options· Required" page:

    1. Leave the SAML 2.0 button checked (we won't be using this)

    2. Application username format should be "Email"

    3. Update application username on should be "Create and update"

    4. Password reveal should be checked

    5. Click the “Done” button

  8. The application has been created but we need to configure the Provisioning API. From the main screen of the App you just created, click the "Provisioning" tab and then the "Configure API Integration" button:

  9. From the "Enable API Integration" page:

    1. Ensure the "Enable API Integration" box is checked

    2. For "Base URL" enter: https://api.app.reclaim.ai/scim/v2

    3. For "API Token" enter "Bearer RECLAIM_API_KEY" you created at the start of this guide. For example, if your RECLAIM_API_KEY was 877dfde9-1676-4ae2-80d5-67c9c0a970e1, you would paste:
      ​
      ​Bearer 877dfde9-1676-4ae2-80d5-67c9c0a970e1
      ​

      in as the value for API Token.
      ​

    4. Click "Test API Credentials"

    5. You should see a notification indicating verification was successful.

    6. Click "Save"

  10. On the "Provisioning" screen click "To App" on the left:

    1. Click the "Edit" button

    2. Check the "Enable" box for:

      1. Create Users

      2. Update User Attributes

      3. Deactivate Users

    3. Click "Save"

The Okta App for SCIM Provisioning on Reclaim.ai has been created and should be ready to use.

Configuring Base Attributes in Okta

You must verify that the attribute mapping between Okta and Reclaim is correct. This will ensure that Reclaim can get the correct data from Okta.

  1. In Okta, select the Reclaim app > Provisioning.

  2. Click into the To App tab on the left-hand side.

  3. Scroll down until you see a table towards the bottom under the Reclaim Attribute Mappings section. On this page, you'll see the default attribute configurations.

  4. Click the pencil icon to the right to change the mapping for any of these attributes. A popup will appear with a dropdown giving options of Okta fields to map to this Reclaim field.

  5. Choose the field from Okta you want to sync into Reclaim and click Save.

Whenever a user is created or updated in Okta, this table tells Okta how to source the value for a particular attribute. If these mappings are not configured correctly, you may notice that some attributes aren't syncing properly.

Configure Reclaim-specific attributes

Reclaim supports other user fields such as an employee's hire date, job category, and location. Since these are not included in the default mappings, you must manually link these fields. This can all be done through the profile editor.

Note: Okta allows you to add any custom attribute (although hire date, job category, and location are common) to Reclaim following the steps below. However, all default fields must be set up for the sync to work correctly.

  1. Within the Provisioning tab, scroll down and click on Go to Profile Editor.

  2. If you don't already have attributes for hire date, job category, location, team, , and role, you can add new attributes by clicking Add attribute.

  3. You will then see a form to enter your values.

  4. Save.

Once you add these attributes, you must populate those values for your users by editing their profiles. Note that none of these additional values are required, but if you define them, you must make sure they have the correct configuration:

Location

  1. Data type: string (example: "Berlin, DE")

  2. Variable name: location

  3. External name: location

  4. External namespace: urn:ietf:params:scim:schemas:extension:reclaimai:2.0:User

  5. Attribute required: Not required (do not select).

  6. Scope: User Personal should be selected.

Hire Date

  1. Data type: date (format: yyyy-MM-dd'T'HH:mm:ssX)

  2. Variable name: hireDate

  3. External name: hireDate

  4. External namespace: urn:ietf:params:scim:schemas:extension:reclaimai:2.0:User

  5. Attribute required: Not required (do not select).

  6. Scope: User Personal should be selected.

Job Category

  1. Data type: string (example: "Software Engineering")

  2. Variable name: jobCategory

  3. External name: jobCategory

  4. External namespace: urn:ietf:params:scim:schemas:extension:reclaimai:2.0:User

  5. Attribute required: Not required (do not select).

  6. Scope: User Personal should be selected.

Organization Role

  1. Data type: string (example: "SRE")

  2. Variable name: orgRole

  3. External name: orgRole

  4. External namespace: urn:ietf:params:scim:schemas:extension:reclaimai:2.0:User

  5. Attribute required: Not required (do not select).

  6. Scope: User Personal should be selected.

Team

  1. Data type: string (example: "Cloud Operations")

  2. Variable name: team

  3. External name: team

  4. External namespace: urn:ietf:params:scim:schemas:extension:reclaimai:2.0:User

  5. Attribute required: Not required (do not select).

  6. Scope: User Personal should be selected.

Other Custom Attributes

Custom attributes created in Reclaim can also be updated via Okta SCIM. The variable name and external name should match the name given to the attribute in Reclaim, converted to camelCase. For example, a custom attribute called "Job Level" should have the following settings configured in Okta:

  1. Data type: string (example: "Manager 4")

  2. Variable name: jobLevel

  3. External name: jobLevel

  4. External namespace: urn:ietf:params:scim:schemas:extension:reclaimai:attributes:2.0:User

  5. Attribute required: Not required (do not select).

  6. Scope: User Personal should be selected.

You have successfully configured Okta to provision users into Reclaim. You must assign your users to the Reclaim SCIM app; otherwise, Okta won't know which users to provision into Reclaim.

Provisioning Users via SCIM

There are two ways of assigning (provisioning) users to the Reclaim.ai SCIM App:

  1. You can assign them individually

  2. You can assign via using an Okta Group

For both, start on the "Assignments" tab of the Reclaim.ai SCIM App screen:

Individual Assignment

In the Reclaim.ai SCIM App, with the "Assignments" tab, click the "Assign" button and then "Assign to People".

You may assign the app to whichever users you want provisioned in Reclaim.ai by clicking "Assign" next to each user; click "Done" when finished. This will then provision, or update, in Reclaim.ai every user that has been assigned.

Group Assignment

As an alternative to individual assignment, you can leverage Okta Groups.

In the Reclaim.ai SCIM App, with the "Assignments" tab, click the "Assign" button and then "Assign to Groups".

You may assign the app to whichever Okta Group you have created by clicking "Assign" next to each group; click "Done" when finished. This will then provision, or update, in Reclaim.ai every user assigned to that Okta group.

Provisioning Time

The time to provision users in Reclaim.ai should be almost immediate, but could depend on the number of users or size of group. It most cases, everything should be complete in a few minutes.

Related Articles
SSO Support (ie: Okta)
Okta SSO Setup Guide - App Catalog
Okta SSO Setup Guide - Bookmark App
Okta SCIM - Import/Sync Existing Users
Did this answer your question?