Usando la API SCIM de Cato para Aplicaciones SCIM Personalizadas

Este artículo describe cómo usar la API SCIM de Cato para el aprovisionamiento de usuarios y grupos de usuarios con un proveedor de identidad (IdP).

Para obtener más información sobre las aplicaciones SCIM personalizadas en el tenant del IdP, consulte Creando una Aplicación SCIM Personalizada para un IdP.

Aplicación SCIM Personalizada de Cato

Para usar una aplicación SCIM personalizada para aprovisionar usuarios y grupos de usuarios a su cuenta de Cato, cree la aplicación en la Aplicación de Gestión de Cato (CMA). Además, necesita mapear los atributos SCIM de Cato a los atributos de su IdP.

Crear una Aplicación SCIM Personalizada en el CMA

Para usar la API SCIM, primero debe crear una aplicación SCIM personalizada en la CMA. Esta aplicación le permite integrar su proveedor de identidad (IdP) con la plataforma de Cato.

Para crear una aplicación SCIM personalizada en la CMA:

1. Desde el menú de navegación, selecciona Acceso > Servicios de Directorio.

2. En la pestaña SCIM, haga clic en Nuevo.

3. Ingrese un nombre para la aplicación.

4. En Proveedor, seleccione Personalizado.

5. Haga clic en Generar Token y copie el valor; no estará disponible después de guardar y necesitará crear un nuevo token. 

6. Haga clic en Guardar.

7. Al llamar a los endpoints de la API SCIM descritos a continuación, necesitará los siguientes valores para autenticarse:

   • URL Base SCIM: Se utiliza como la ruta base para solicitudes de API

   • Token Bearer: Usado para autenticar solicitudes de API

Atributos SCIM de Cato

Estos son los atributos SCIM para usuarios y grupos de usuarios de Cato que necesita mapear con los atributos correspondientes del IdP.

Entendiendo la API SCIM de Cato

Autenticando a la API SCIM de Cato

Los clientes se autentican a la API SCIM usando autenticación de token bearer, según lo definido por RFC 6750. Todas las solicitudes de API deben incluir los siguientes encabezados HTTP:

Authorization: Bearer <access_token>
Content-Type: application/json

Puede obtener el token de acceso desde la Aplicación de Gestión de Cato.

Camino Base para los Puntos Finales SCIM

Todos los puntos finales de la API SCIM usan el siguiente camino base:

/scim/v2/{accountId}/{sourceId}

Parámetros del Camino: 

• accountId (string): Identificador único de su cuenta de arrendatario de Cato

• sourceId (integer): Un identificador asignado por Cato para representar de manera única una integración específica de IdP

Estos parámetros son requeridos en todas las solicitudes, pero se omiten de los caminos de puntos finales individuales en este artículo para brevedad.

Gestionando Usuarios

Esta sección describe cómo crear, actualizar, eliminar y recuperar entidades de usuario SCIM usando la API SCIM de Cato.

Crear un Usuario

Método HTTP:POST /Users 

Campos Requeridos: 

• userName (string): Nombre de usuario único (por ejemplo, dirección de correo electrónico)

• externalId (string): Identificador externo del IdP

• active (boolean): Debe ser true para activar al usuario

Nota:id es devuelto por el servicio SCIM y debe ser usado en llamadas API subsecuentes. externalId es opcional y no puede ser usado en caminos de API.

Respuesta: 

• Estado: 201 Creado

Errores: 

• 400 Solicitud Incorrecta: Esquema no válido

• 401 No Autorizado 

• 409 Conflicto: Duplicar userName o externalId

Actualizar un Usuario

PUT

Método HTTP:PUT /Users/{id} 

Campo Requerido: 

• id: ID SCIM Interno de Cato

Respuesta: 

• Estado: 200 OK

Errores: 

• 401 No Autorizado 

• 404 No Encontrado 

• 409 Conflicto: Duplicar userName o externalId

PATCH

Método HTTP:PATCH /Users/{id} 

Respuesta: 

• Estado: 200 OK

Errores: 

• 400 Solicitud incorrecta: esquema o sintaxis de parche incorrecta

• 401 No Autorizado 

• 404 No Encontrado 

• 409 Conflicto: Identificadores duplicados

Eliminar un Usuario

Método HTTP:DELETE /Users/{id}

Respuesta:

• Estado: 204 Sin Contenido

Esto es una eliminación suave. El usuario permanece en el sistema pero no se devuelve en búsquedas.

Obtener un Usuario por ID

Método HTTP:GET /Users/{id}

Respuesta:

• Estado: 200 OK

Errores:

• 401 No autorizado

• 404 No encontrado

Buscar Usuarios

Método HTTP:GET /Users

Parámetros de Consulta:

• filter: Consulta para filtrar usuarios (por ejemplo, userName eq "user@domain.com")

• count (opcional)

• startIndex (opcional)

Filtros Soportados:

• Solo se soporta eq

• Atributos soportados: userName, email, givenName, familyName

• Los filtros compuestos solo se respaldan en este formato:

  filter=emails[type eq "work"] and email eq "bob@cato.com"

Respuesta:

• Estado: 200 OK

Errores:

• 401 No autorizado

Gestionar Grupos

Esta sección explica cómo usar la API SCIM para crear, actualizar, eliminar y recuperar entidades de grupo en tu entorno de Cato.

Crear un Grupo

Método HTTP:POST /Groups

Respuesta:

• Estado: 201 Creado

Errores:

• 401 No autorizado

• 409 Conflicto: displayName o ID del objeto duplicado

Actualizar un Grupo

PUT

Método HTTP:PUT /Groups/{id}

Respuesta:

• Estado: 200 OK

Errores:

• 401 No autorizado

• 404 No encontrado

• 409 Conflicto

PATCH

Método HTTP:PATCH /Groups/{id}

Rutas de parcheo compatibles:

• displayName

• miembros

Respuesta:

• Estado: 200 OK

Errores:

• 400 Solicitud incorrecta: esquema o sintaxis de parche incorrecta

• 401 No autorizado

• 404 No encontrado

• 409 Conflicto

Eliminar un Grupo

Método HTTP:DELETE /Groups/{id}

Respuesta:

• Estado: 204 Sin Contenido

Importante:

Esto es una eliminación total. El grupo se elimina permanentemente.

Obtener un Grupo por ID

Método HTTP:GET /Groups/{id}

Parámetros de Consulta Opcionales:

• excludeAttributes (por ejemplo, members)

Respuesta:

• Estado: 200 OK

Errores:

• 401 No autorizado

• 404 No encontrado

Buscar Grupos

Método HTTP:GET /Groups

Parámetros de Consulta:

• filter: Solo se admite displayName eq "Group Name"

• count (opcional)

• startIndex (opcional)

Los filtros compuestos o operadores no admitidos devuelven todos los grupos sin filtrar.

Respuesta:

• Estado: 200 OK

Errores:

• 401 No autorizado

Notas

Comportamiento del campo id en la creación

• El campo id es opcional en las solicitudes de creación de usuarios y grupos.

• Si se omite, el servicio SCIM genera un id único.

• Siempre usa el valor de id devuelto en las llamadas posteriores a la API.

Importante:

Evita usar IDs generados por el cliente a menos que sea necesario. El ID de SCIM es el identificador autorizado.

Comportamiento de Eliminación

• La eliminación de usuarios a través de DELETE /Users/{id} realiza una eliminación suave al establecer el campo active en false. El usuario es recuperable a través de GET /Users/{id} pero se excluye de los resultados de GET /Users.

• La eliminación de grupos a través de DELETE /Groups/{id} realiza una eliminación completa. El grupo se elimina permanentemente.