Netskope Global Technical Success (GTS)
Endpoint in REST API V2 para la gestión de usuarios y grupos
Netskope Cloud Version - 126
Objetivo
Utilizar los endpoints REST API V2 SCIM para crear manualmente usuarios y grupos SCIM.
Contexto
Los usuarios creados manualmente no se designan automáticamente como usuarios SCIM. Por lo tanto, reciben el valor predeterminado steering configuration profile ("Default tenant config") y el valor predeterminado client configuration profile ("Default tenant config"). Esta asignación automática se produce porque la aplicación del perfil para la configuración del sistema operativo y del cliente requiere la pertenencia a un grupo.
Como solución alternativa, podríamos aprovechar la API REST V2 para la creación de usuarios y grupos. De esta forma, los usuarios se convertirían en usuarios SCIM, lo que significa que podrían insertarse en grupos y, por lo tanto, aplicar perfiles de configuración y dirección personalizados.
| ⚠️ Importante
|
Prerrequisito
Puede utilizar cualquier aplicación capaz de enviar solicitudes HTTP. En este artículo se muestra cómo utilizar Postman (https://www.postman.com/), una herramienta en la que se puede introducir directamente la URL de la solicitud (véase más abajo).
| ℹ️ Importante saber MÉTODOS HTTP
CÓDIGOS DE RESPUESTA HTTP
Herramienta Swagger REST API V2 Cada tenant de Netskope proporciona un enlace directo a su herramienta Swagger (DOCUMENTACIÓN DE LA API). Los administradores pueden acceder a esta herramienta a través de Settings > Tools > API REST v2». La herramienta Swagger permite a los administradores revisar la sintaxis y probar las llamadas a la API REST v2 para su tenant específico.
|
Antes de comenzar
Es necesario crear un token REST API V2 con endpoints SCIM.
Paso n.º 1: asegúrese de que la API REST V2 esté habilitada.
Path: Netskope Tenant UI >>> Tools >>> REST API V2
- Si no está habilitado, haga clic en el lápiz debajo de «REST API STATUS y configúrelo como «Habilitado».
Paso n.º 2 - Crear un token SCIM
Path: Netskope Tenant UI >>> Tools >>> REST API V2
- Clic en “New Token”, agregar un nombre de token, buscar los siguientes endpoints y proporcionar privilegios de lectura y escritura al token.
- Clic en “Save” y asegurarse de guardar el token de la API REST V2 haciendo clic en «COPY TOKEN», como se muestra a continuación.
| ℹ️ Variables
*Las variables de cada solicitud se resaltarán como se muestra arriba. |
Creación de un nuevo usuario SCIM
Al crear un nuevo usuario SCIM, se tendrá que enviar un POST a /api/v2/scim/Users como se muestra a continuación.
| 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" } }' |
Después de ejecutar lo anterior, se espera recibir un código de retorno HTTP: 201 (OK). Además del código de retorno «201 (OK)», dentro del cuerpo de la respuesta, se recibirá el ID del nuevo usuario. Consulte el siguiente ejemplo:
Recuperar la información del nuevo usuario.
Para extraer la información del usuario que se acabó de crear:
| 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' |
Por otro lado, puede extraer los primeros 1000 usuarios enviando:
| 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' |
Crear un nuevo grupo
Para crear un nuevo grupo vacío, se tendrá que enviar un POST a /api/v2/scim/Groups como se muestra a continuación.
| 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" } }' |
También se puede añadir usuarios mientras se crea el grupo con lo siguiente:
| 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" } }' |
Si la ejecución se realiza correctamente, se espera un código de estado HTTP 201 (OK). El cuerpo de la respuesta contendrá entonces el ID del grupo recién creado.
Recuperar la información del nuevo grupo.
Para extraer la información del grupo que se acabó de crear:
| 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' |
Por otro lado, se puede extraer los primeros 1000 grupos enviando:
| 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' |
Añadir un usuario a un grupo
Para añadir un usuario a un grupo, se tendrá que enviar una petición tipo PATCH a /api/v2/scim/Groups, tal y como se muestra a continuación.
| 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>" } ] } ] }' |
| ℹ️ En la solicitud REST API anterior se tuvo la operación «add» (añadir), como se muestra a continuación en la captura de pantalla tomada de Swagger, las operaciones disponibles son: Add (Añadir), Remove (Eliminar), Replace (Reemplazar).
|
Tras una ejecución correcta, la respuesta HTTP esperada es un código de estado 204 (OK) con un cuerpo de respuesta vacío, tal y como se ilustra en el ejemplo siguiente.
También se puede comprobar en el estado del tenant buscando los miembros del grupo que se han creado anteriormente.
Path: Netskope Tenant UI >>> Security Cloud Platform >>> Netskope Client >>> Groups
- Haga clic en la configuración del grupo, luego en «Ver detalles» o envíe una invitación (cuando esté listo para implementar).
- La interfaz te mostrará los miembros del grupo.
Ahora se puede crear un nuevo perfil de steering configuration o client configuration y asignarlo al grupo recién creado.
Términos y condiciones
- Toda la información documentada se somete a pruebas y verificaciones para garantizar su exactitud.
- En el futuro, es posible que el proveedor modifique la funcionalidad de la aplicación. Si se nos comunica algún cambio de este tipo, actualizaremos inmediatamente la documentación para reflejarlo.
Notas
- Este artículo ha sido redactado por Netskope Global Technical Success (GTS).
- Para cualquier otra consulta relacionada con este artículo, póngase en contacto con Netskope GTS enviando un caso de soporte técnico con 'Case Type – How To Questions'.
