Netskope Global Technical Success (GTS)
Endpoint in REST API V2 for User and Group Management
Netskope Cloud Version - 126
Objective
Utilize REST API V2 SCIM endpoints to manually create SCIM users and groups.
Context
Manually created users are not automatically designated as SCIM users. Consequently, they receive the default steering configuration profile ("Default tenant config") and the default client configuration profile ("Default tenant config"). This automatic assignment occurs because profile application for steering and client configurations necessitates group membership.
As a workaround, we could leverage REST API V2 for Users and Groups creation, by doing this, the users will become SCIM users, meaning that they are able to be inserted into Groups, therefore apply custom steering and configuration profiles.
| ⚠️ Important
|
Prerequisite
You can use any application capable of sending HTTP requests. This article will demonstrate using Postman (https://www.postman.com/), a tool where you can directly input the request URL (see below).
| ℹ️ Important to know HTTP METHODS
HTTP RESP CODE
Swagger REST API V2 tool Each Netskope tenant provides a direct link to its Swagger tool (API DOCUMENTATION). Tenant administrators can access this tool via "Settings > Tools > REST API V2". The Swagger tool allows administrators to review the syntax and test REST API v2 calls for their specific tenant.
|
Before we begin
A REST API V2 token with SCIM endpoints needs to be created.
Step #1 - Ensure that REST API V2 is enabled.
Path: Netskope Tenant UI >>> Tools >>> REST API V2
- If not enabled, click on pen under “REST API STATUS” and set this up to “Enabled”
Step #2 - Create a SCIM token
Path: Netskope Tenant UI >>> Tools >>> REST API V2
- Click on “New Token”, add a token name, search for the below endpoints and provide read and write privilege to the token
- Click on “Save” and ensure you save the REST API V2 token by clicking the “COPY TOKEN” as shown below
| ℹ️ Variables
*The variables of each requests will be highlighted like above |
Creating a new SCIM User
When creating a new SCIM User, we will need to send a POST against /api/v2/scim/Users as shown below
| curl --location --request POST 'https://<TENANT-HOSTNAME>/api/v2/scim/Users' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Netskope-Api-Token: <API-TOKEN>' \ --data-raw '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "<UPN>", "name": { "familyName": "<FAMILY-NAME>", "givenName": "<GIVEN-NAME>" }, "active": true, "emails": [ { "value": "<EMAIL>", "primary": true } ], "externalId": "User-Ext_id", "meta": { "resourceType": "User" } }' |
After executing the above, we expect to receive a http return code: 201 (OK).
In addition to the return code “201 (OK)”, within the response body, we will receive the new user’s ID. Please refer to the below example:
Retrieve the new User’s information
To pull the user’s information we just created, you can send the following:
| curl --location --request GET 'https://<TENANT-HOSTNAME>/api/v2/scim/Users/<USER-ID>'\ --header 'accept: application/scim+json;charset=utf-8' \ --header 'Netskope-Api-Token: <API-TOKEN>’ \ --header 'Content-Type: application/scim+json;charset=utf-8' |
On the other hand, you can pull the first 1000 Users by sending:
| curl --location --request GET 'https://<TENANT-HOSTNAME>/api/v2/scim/Users'\ --header 'accept: application/scim+json;charset=utf-8' \ --header 'Netskope-Api-Token: <API-TOKEN>’ \ --header 'Content-Type: application/scim+json;charset=utf-8' |
Creating a new group
To create an empty new group, we will need to send a POST against /api/v2/scim/Groups as shown below
| curl --location --request POST 'https://<TENANT-HOSTNAME>/api/v2/scim/Groups' \ --header 'accept: application/scim+json;charset=utf-8' \ --header 'Netskope-Api-Token: <API-TOKEN>' \ --header 'Content-Type: application/scim+json;charset=utf-8' \ --data '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "<GROUP-NAME>", "members": [ { "value": "" } ], "externalId": "Group-Ext_id", "meta": { "resourceType": "Group" } }' |
We could also add Users while creating the group with the following:
| curl --location --request POST 'https://<TENANT-HOSTNAME>/api/v2/scim/Groups' \ --header 'accept: application/scim+json;charset=utf-8' \ --header 'Netskope-Api-Token: <API-TOKEN>' \ --header 'Content-Type: application/scim+json;charset=utf-8' \ --data '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "<GROUP-NAME>", "members": [ { "value": "<USER-ID-1>", "value": "<USER-ID-2>", "value": "<USER-ID-3>" } ], "externalId": "Group-Ext_id", "meta": { "resourceType": "Group" } }' |
Upon successful execution, expect an HTTP status code of 201 (OK). The response body will then contain the ID of the newly created group.
Retrieve the new Group’s information
To pull the Group’s information we just created, you can send the following:
| curl --location --request GET 'https://<TENANT-HOSTNAME>/api/v2/scim/Groups/<GROUP-ID>'\ --header 'accept: application/scim+json;charset=utf-8' \ --header 'Netskope-Api-Token: <API-TOKEN>’ \ --header 'Content-Type: application/scim+json;charset=utf-8' |
On the other hand, you can pull the first 1000 Groups by sending:
| curl --location --request GET 'https://<TENANT-HOSTNAME>/api/v2/scim/Groups/'\ --header 'accept: application/scim+json;charset=utf-8' \ --header 'Netskope-Api-Token: <API-TOKEN>’ \ --header 'Content-Type: application/scim+json;charset=utf-8' |
Add an User into a Group
To add an User into a group, you we will need to send a PATH against /api/v2/scim/Groups as shown below
| curl --location --request PATCH 'https://<TENANT-HOSTNAME>/api/v2/scim/Groups/<GROUP-ID>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Netskope-Api-Token: <API-TOKEN>' \ --data '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations":[ { "op":"add", "path": "members", "value":[ { "value": "<USER-ID>" } ] } ] }' |
| ℹ️ In the above REST API request we have the add operation, as shown below on the screenshot taken from the Swagger, the available operations are: Add, Remove, Replace |
Upon successful execution, the expected HTTP response is a 204 (OK) status code with an empty response body, as illustrated in the example below.
We can also check on the tenant by searching for the members of the group we previously created.
Path: Netskope Tenant UI >>> Security Cloud Platform >>> Netskope Client >>> Groups
- Click on group’s setting, then “View Details” or send invitation (when you’re ready to deploy)
- The interface will show you the group’s members
A new Steering or Client configuration profile can now be created and assigned to the newly created group.
Terms and Conditions
- All documented information undergoes testing and verification to ensure accuracy.
- In the future, it is possible that the application's functionality may be altered by the vendor. If any such changes are brought to our attention, we will promptly update the documentation to reflect them.
Notes
- This article is authored by Netskope Global Technical Success (GTS).
- For any further inquiries related to this article, please contact Netskope GTS by submitting a support case with 'Case Type – How To Questions'.
