Tech admin
Any Gong plan*
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 team members have the necessary Gong seat. Features that require seats won't be available until seats are assigned.
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:
Go to your company settings page > PEOPLE area > Team Member Provisioning.
Select Custom as the provisioning source.
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.
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.
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:
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
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
In Gong, go to your company settings page > PEOPLE area > Team Member Provisioning.
Create an assignment to assign data capture, workspace, and permission settings:
In the Assign settings area, click ADD ASSIGNMENT.
Give the assignment a name.
In the custom SCIM source groups area, select the group you want to define the settings for.
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.
In the Workspaces and permissions area, set the permissions profile for each workspace in your organization.
In the Data capture area, select which data should be captured and imported to Gong. For details see About managing team members.
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.
Click ADD ASSIGNMENT.
Click SAVE.