Skip to main content
Gainsight Inc.

Okta Gainsight SCIM Setup

  1. Last updated
  2. Save as PDF
This article explains how to configure System for Cross-domain Identity Management (SCIM) integration between Okta and Gainsight. SCIM enables automated user provisioning and de-provisioning.

This article explains how to configure SCIM (System for Cross-domain Identity Management) integration between Okta and Gainsight. SCIM enables automated user provisioning and de-provisioning.

Overview

SCIM integration automates the provisioning lifecycle of users in Gainsight by connecting with your identity provider, Okta. Once configured, the SCIM integration allows you to:

  • Automatically create, update, and deactivate users in Gainsight based on Okta assignments.
  • Synchronize user profile attributes and custom fields between systems.
  • Improve security and efficiency by managing access centrally through Okta.

This guide outlines the full setup process in Okta, including SAML configuration, SCIM connector settings, OAuth authentication, and optional custom field mappings.

Prerequisite

To complete the setup process, admins must have access to both Okta and Gainsight.

Gainsight recommends using separate Okta applications for SAML authentication and SCIM provisioning to avoid configuration conflicts and ensure reliable user authentication and provisioning.

Create SCIM Application in Okta

  1. Log in to your Okta Admin Console.
  2. Click Create Application.
  3. Select SAML 2.0, click Next.
  4. Under General Settings, enter Gainsight SCIM Integration as the app name.
  5. Click Next.

creat SAML.png

  1. Configure the following using metadata.xml from Gainsight:
  2. Click Next > Finish.

Enable SCIM Provisioning

After the app is created, you can enable the SCIM provisioning:

  1. Navigate to the General tab.
  2. Click Edit. The App Settings dialog appears.
  3. Under the Provisioning option, select SCIM.
  4. Click Save. The Proviosing tab is now enabled

Enable SCIM.png

  1. Configure the below details in the Provisioning tab.

Provision tab.png

 

Field

Value

SCIM Connector Base URL

https://<your-gainsight-tenant-url>/v1/users/services/scim

Unique Identifier Field for Users

userName

Supported Provisioning Actions

  • Import New Users and Profile Updates

  • Push New Users

  • Push Profile Updates

Authentication Mode: OAuth 2.0

  • Create an OAuth App in Gainsight to obtain

    • Client ID

    • Client Secret

For more information on OAuth, refer to the OAuth for Gainsight APIs

Access Token Endpoint URI

https://<your-gainsight-tenant-url>/v1/users/oauth/access/token

Authorization Endpoint URI

https://<your-gainsight-tenant-url>/v1/authorize?clientId=<<clinetId_from_Gainsight_OAuth>>&redirectUri=https://system-admin.okta.com/admin/app/cpc/<<please_enter_okta_application_name>>/oauth/callback&scopes=read_write

For more information on configuring the callback URL, refer to the Okta SCIM Provisioning Integration – Authentication
  1. Click the Authenticate with Gainsight SCIM Integration and authorize Gainsight. 

Add Custom Field Mappings

Gainsight supports custom fields in SCIM APIs with the following data types:

  • Boolean
  • String
  • Picklist
  • Multi-Picklist

Gainsight recommends contacting Gainsight Support to add the same mappings on the Gainsight instance. This ensures that the fields are included in the User Create and Update APIs.

To configure these fields in Okta:

  1. Navigate to Directory > Profile Editor.
  2. Select your SCIM integration app.
  3. Click +Add Attribute.
    Note: The Gainsight SCIM external namespace is urn:ietf:params:scim:schemas:extension:gainsight:2.0:User
     

Okta Profile Editor view showing the Gainsight SCIM Integration User profile with display name, variable name, and attribute list including username and names.
 

Here are few examples of data types supported in SCIM API:

  • Boolean Field: IsSuperAdmin
    Gainsight includes an internal field that identifies whether a user is a Super Admin. By default, users are not marked as Super Admins.
    To manage this attribute via SCIM:
    • Create a custom Boolean field in Okta.
    • Set the attribute name to exactly IsSuperAdmin.
      Note: If the name does not match, Gainsight will not recognize or update the Super Admin status.

      Add Attribute form showing configuration fields for the IsSuperAdmin attribute, including data type Boolean, display name, variable name, and external name.

      You can choose whether the attribute type is Personal or Group, depending on the level at which you want the attribute to be applied.
  • String and Picklist Field: License Type
    Gainsight requires a License Type when a user is created. If no value is passed, the user is assigned the Internal Collaborator license by default. 
    To pass the license type via SCIM:
    • Create a custom String field in Okta
    • Set the attribute name to exactly LicenseType

      Add Attribute form for LicenseType showing string data type, display and variable names, external namespace, and an enumerated list with Full and Viewer options.

      You can use one of the following values, and they must match exactly:
      • Full
      • Viewer
      • Viewer_Analytics
  • Multi-Picklist

    Add Attribute form for Department showing string array data type, display and variable names, and enumerated values including Support, Services, and Engineering.
     

Manage Gainsight Attributes Using Okta Groups

In Okta, you can configure your Gainsight custom attributes at the group level. When you configure attributes (such as LicenseType, IsSuperAdmin, or any other supported custom field) on an Okta group, every user assigned to that group inherits the same values automatically.

To configure group level custom attributes, follow these steps:

  1. Navigate to Applications > Assignments in Okta.
  2. Under Filters, select Groups.

    GainsightSCIM application assignments page displaying group-based assignments with priority order and options to edit or remove Test and Viewer roles.
     
  3. Choose the Okta group you want to assign to the Gainsight application, then click Assign.

    Assign GainsightSCIM to Groups window showing available groups Everyone and Viewer, with an Assign action highlighted for adding the app to the Viewer group.
     

  4. Enter the attribute values for the custom fields you created. For example: LicenseType or IsSuperAdmin.

    Assign GainsightSCIM to Groups settings showing default user attributes like preferred language, locale, timezone, and user type with options to override values.
     

  5. Click Save and Go Back.

    Group assignment settings displaying LicenseType and IsSuperAdmin fields with override options, and a highlighted Save and Go Back button for confirming changes.
     

After this configuration, any user added to the group automatically receives the attribute values defined for that group.

User Assigned to Multiple Groups

If a user is assigned to multiple Okta groups, Okta determines which attribute values to apply using group priority.

The group with the highest priority provides the attribute values that Gainsight receives through SCIM for user creation and updates.

GainsightSCIM assignments page showing Test and Viewer group assignments with priority order, edit and remove options, and self-service settings information.
 

Note: If attribute values appear incorrect in Gainsight, check the user’s group assignments and confirm which group has the highest priority.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    1. Gainsight Integration
    2. Okta Integration
    3. SCIM Setup