This article is a very 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.
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.
-
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
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 <ouath_token>"
-
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" : "acme.user@acme.com", "name" : { "familyName" : "User", "givenName" : "Acme" }, "displayName" : "Acme User", "title" : "Software Engineer", "locale" : "en-US", "active" : true, "emails" : [ { "value" : "acme.user@acme.com", "type" : "work", "primary" : true } ], "phoneNumbers" : [ { "value" : "" } ], "groups" : [ ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : { "manager" : { "email" : "acme.manager@acme.com" } } }
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" : "acme.user@acme.com", "name" : { "familyName" : "User", "givenName" : "Acme" }, "displayName" : "Acme User", "title" : "Senior Software Engineer", "locale" : "en-US", "active" : true, "emails" : [ { "value" : "acme.user@acme.com", "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" : "acme.manager@acme.com", } } }
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" : "acme.user@acme.com",
"name" : {
"familyName" : "User",
"givenName" : "Acme"
},
"displayName" : "Acme User",
"title" : "Senior Software Engineer",
"locale" : "en-US",
"active" : false,
"emails" : [ {
"value" : "acme.user@acme.com",
"type" : "work",
"primary" : true
} ],
"phoneNumbers" : [ {
"value" : ""
} ],
"groups" : [ ],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" : {
"manager" : {
"email" : "acme.manager@acme.com"
}
}
}
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)