Provision team members from a custom source (SCIM)

This article is a technical guide intended for people who want to develop their own provisioning source to use with Gong. Automatic provisioning is supported from these sources.

This article explains how to set up automatic provisioning by creating an integration with Gong and your IDP using standard OAuth and SCIM protocols.

This article is intended for tech admins with engineering capabilities who would like to automatically provision people from their identity provider.

Automatic provisioning with SCIM is also supported by connecting to identity providers that support SCIM, such as Okta and Rippling. For more info, see Provisioning team members.

When setting up provisioning, ensure that you assign the necessary Gong seats for your team members. If you enable settings that require a seat, but don't assign the seat, the features won't be available for those team members. Once the seat is assigned the permissions and settings will be enabled for the team members.

Supported features

• Provision new users: New users created in the custom source will also be provisioned in Gong. See Create a user, below.

• Provision user updates: Updates made to the user's profile in the custom source will be pushed to Gong. See Update a user, below.

• Provision user deactivation: Deactivating the user or disabling the user's access to Gong through the custom source will deactivate the user in Gong. See Deactivate a user, below.

• Provision new groups: New groups created in the custom source will be mastered by the custom source. See Create a group, below.

• Provision user update to group: Add a user to a group. See Add a user to a group, below.

• Provision user removal from group: Remove a user from a group. See Remove a user from a group, below.

• Provision group removal: Remove a group. See Delete a group, below.

Configure the custom source in Gong

Follow these steps to enable automatic provisioning from a generic SCIM source:

1. Go to your company settings page > PEOPLE area > Team Member Provisioning.

2. Select Custom as the provisioning source.

3. A default assignment is set up where team members imported with this assignment are not assigned any seats, data capture capabilities or permissions. You can edit this or set up assignments for different teams.

4. Generate an OAuth bearer token to send with each SCIM provisioning request. See Generate the OAuth bearer token, below.

   When you have the bearer token, you can send SCIM provisioning requests.

5. Send the required SCIM provisioning requests. See Supported features, above, and the Sample requests, below.

About SCIM

SCIM (System for Cross-domain Identity Management) specification, is an open standard designed to manage user identity information.

SCIM defines a number of HTTP endpoints that handle requests containing data formatted in JSON.

Gong's base SCIM URL is provisioning.gong.io

For more guidance, check these SCIM references:

• http://www.simplecloud.info

• https://tools.ietf.org/html/rfc7644

Generate the OAuth bearer token

To talk to the service, you need a secret token. SCIM clients (i.e., you!) acquire the token through a standard OAuth exchange. It requires a few lines of code on your side, and a redirect endpoint as part of the SCIM implementation.

Acquire the OAuth bearer token

Who can do this?

Acquire the bearer token using the standard OAuth flow, as described in the article Create an app for Gong.

Sample requests

Notes:

• Add the OAuth token as the "Authorization" HTTP header in this format: "Bearer "

• Add the following HTTP header in each request:

  Name: "User-Agent"

  Value: "custom-scim"

Further reading:

This guide to provisioning with Okta may be helpful to you for the expected values of the different attributes.

Create a user

HTTP method: POST

Endpoint: https://provisioning.gong.io/scim/v2/Users

{
 "schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:User", 
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ],
  "externalId" : "aaasdss556565",
 "userName" : "[email protected]",
 "name" : {
  "familyName" : "User",
   "givenName" : "Acme"
  },
  "displayName" : "Acme User",
  "title" : "Software Engineer",
  "locale" : "en-US",
  "active" : true,
  "emails" : [ {
 "value" : "[email protected]",
    "type" : "work",
    "primary" : true
  } ],
  "phoneNumbers" : [ {
   "value" : ""
  } ],
 "groups" : [ ],
 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
    "manager" : {
   "email" : "[email protected]"
  }
 }
}

The response is the same JSON that you sent, with the addition of the "id" attribute, which is the ID of the user at Gong, to be used in the update requests.

Update a user

Similar to the “create” request, in this example we update the phone number and the title.

HTTP method: PUT

Endpoint: https://provisioning.gong.io/scim/v2/Users/ {id} (the user ID)

Sample request body:

{
  "schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:User", 
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ],
  "id" : "1846369656179510550",
  "externalId" : " aaasdss556565 ",
  "userName" : "[email protected]",
  "name" : {
    "familyName" : "User",
    "givenName" : "Acme"
  },
  "displayName" : "Acme User",
  "title" : "Senior Software Engineer",
  "locale" : "en-US",
  "active" : true,
  "emails" : [ {
    "value" : "[email protected]",
    "type" : "work",
    "primary" : true
  } ],
  "phoneNumbers" : [ {
    "value" : ""
  }, {
    "value" : "555 5555 555",
    "type" : "work",
    "primary" : true
  } ],
  "groups" : [ ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
    "manager" : {
      "email" : "[email protected]",
    }
  }
}

Deactivate a user

In this example, the "active" attribute is set to false.

HTTP method: PUT

Endpoint: https://provisioning.gong.io/scim/v2/Users/ {id} (the user ID)

Sample request body:

{
 "schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:User", 
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ],
  "id" : "1846369656179510550",
  "externalId" : " aaasdss556565 ",
  "userName" : "[email protected]",
  "name" : {
    "familyName" : "User",
    "givenName" : "Acme"
  },
  "displayName" : "Acme User",
  "title" : "Senior Software Engineer",
  "locale" : "en-US",
  "active" : false,
  "emails" : [ {
    "value" : "[email protected]",
    "type" : "work",
    "primary" : true
  } ],
  "phoneNumbers" : [ {
    "value" : ""
  } ],
  "groups" : [ ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
    "manager" : {
      "email" : "[email protected]"
    }
  }
}

Update user's spoken languages

This example shows how to use custom SCIM attributes to specify a user’s spoken languages. To see which BCP-47 language codes are supported by SCIM, see this.

HTTP method: PUT

Endpoint: https://provisioning.gong.io/scim/v2/Users/ {id} (the user ID)

Sample request body:

{
2 "schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:User", 
3"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ],
4  "id" : "1846369656179510550",
5  "externalId" : " aaasdss556565 ",
6  "userName" : "[email protected]",
7  "name" : {
8    "familyName" : "User",
9    "givenName" : "Acme"
10  },
11  "displayName" : "Acme User",
12  "title" : "Senior Software Engineer",
13  "locale" : "en-US",
14  "active" : true,
15  "emails" : [ {
16    "value" : "[email protected]",
17    "type" : "work",
18    "primary" : true
19  } ],
20  "phoneNumbers" : [ {
21    "value" : ""
22  } ],
23  "groups" : [ ],
24  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
25    "manager" : {
26      "email" : "[email protected]"
27    }
28  },
29  "urn:ietf:params:scim:schemas:extension:Gong:2.0:User": {
30    "spokenLanguages": [
31      {
32        "language": "en-AB",
33        "primary": false
34      },
35      {
36        "language": "it-IT",
37        "primary": true
38      },
39      {
40        "language": "af-ZA",
41        "primary": false
42      }
43    ]
44  }
45}

Create a group

HTTP method: POST

Endpoint: https://provisioning.gong.io/scim/v2/Groups

Sample request body:

{
"schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:Group" ],
"displayName" : "Acme Test Group",
"members" : [ ]
}

The response is the same JSON as sent with the addition of "id" attribute, which is the Id of the group (at Gong), to be used in the update requests.

Add a user to a group

HTTP method: PATCH

Endpoint: https://provisioning.gong.io/scim/v2/Groups/ {id} (the group ID)

Sample request body:

{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
    "op":"add",
    "path”:"members",
    "value":[
           {
              "value":"1846369656179510550"
           }
        ]
      }
    }
  ]
}

Remove a user from a group

HTTP method: PATCH

Endpoint: https://provisioning.gong.io/scim/v2/Groups/ {id} (the group ID)

Sample request body:

{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
      "op":"remove",
      "path":"members[value eq \"1846369656179510550\"]"
    }
  ]
}

Delete a group

HTTP method: DELETE

Endpoint: https://provisioning.gong.io/scim/v2/Groups/ {id} (the group ID)

Create automatic assignments in Gong

1. In Gong, go to your company settings page > PEOPLE area > Team Member Provisioning.

2. Create an assignment to assign data capture, workspace, and permission settings:

   1. In the Assign settings area, click ADD ASSIGNMENT.

   2. Give the assignment a name.

   3. In the custom SCIM source groups area, select the group you want to define the settings for.

   4. Select the Gong seats you want team members in this group to have assigned to them.

      Note

      Ensure you assign the Gong seats required for the permissions and other settings included in the assignment.

   5. In the Workspaces and permissions area, set the permissions profile for each workspace in your organization.

   6. In the Data capture area, select which data should be captured and imported to Gong. For details see About managing team members.

   7. In the Update settings area, define how settings can be managed for this assignment:

      • Select Manual editing to manage data capture and permission settings for users in this assignment in Gong.

        After you create the assignment: if you make changes to group settings in Okta, they will not be pushed to Gong. However, you can edit the group settings manually in Gong.

      • Select Automatic updates to give Okta governance over data capture and permission settings in Gong.

        Define data capture and permission settings in Gong only when creating an assignment. Thereafter, other changes will only be applied to users in groups with this assignment when pushed from Okta.

   8. Click ADD ASSIGNMENT.

3. Click SAVE.