Puntos finales de la API del servidor SCIM de Drupal
Noticias
Este documento describe los puntos finales SCIM necesarios para habilitar el aprovisionamiento y desaprovisionamiento de usuarios SCIM. SCIM es un protocolo estándar de la industria que permite automatizar las operaciones CRUD de los usuarios. móduloEl sitio Drupal podrá actuar como servidor SCIM. Esto significa que cualquier cambio realizado en el proveedor de identidad (es decir, el cliente SCIM) se sincronizará con el sitio Drupal.
Descripción general de SCIM
- Versión del protocolo: SCIM 2.0
- Ruta base: URL base/scim
- Recursos de apoyo: Usuarios, Grupos
- Formato de datos: JSON
Autenticación y encabezados
- Autorización: Token de portador
- Tipo de contenido: aplicación / json
- Aceptar: aplicación / json
Operaciones API compatibles
Se admiten las siguientes operaciones de API
Puntos finales del usuario
- Desactivar usuario
- Obtener usuario
- Lista de usuarios
- Actualización de usuario (PARCHE)
- Actualizar usuario (PUT)
- Crear usuario (POST)
Puntos finales del grupo
- Grupos de listas
- Obtener grupo por ID
- Crear un grupo
- Actualizar grupo [Atributos de no miembros]
- Grupo de actualización [Miembros]
- Eliminar grupo
Puntos finales del usuario
1. Desactivar usuario (PATCH)
- Errores:
- Solicitud de ejemplo:
- Ejemplo de respuesta - 204 Sin contenido.
Para desactivar o eliminar un usuario en Drupal, debe habilitar las opciones necesarias en el módulo. Estas opciones están disponibles en la página de configuración del módulo.
PARCHE /Usuarios/{id-usuario}| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| Excepción no encontrada del recurso | El usuario especificado no existe. | 404 |
PATCH /Usuarios/{id-usuario} HTTP/1.1 Tipo de contenido: aplicación/json Autorización: Portador { "Operaciones": [ { "op": "Reemplazar", "ruta": "activo", "valor": falso } ] }
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "4", "userName": "nombre de usuario", "active": , "emails": [{ "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" }], "meta": { "resourceType": "User" } }
2. Buscar usuario por su ID
- Errores:
- Solicitud de ejemplo:
- Respuesta de ejemplo:
- 404 No encontrado.
- 200 Ok encontrado.
Para obtener un usuario existente, realice una solicitud GET a / Usuarios utilizando su ID de usuario.
OBTENER /Usuarios/{id-usuario}| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| Excepción no encontrada del recurso | El usuario especificado no existe. | 404 |
GET /Users/{user-id} HTTP/1.1 Autorización: Portador { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Usuario no encontrado", "status": 404 }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "4", "userName": "nombre de usuario", "active": 1, "emails": [ { "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" } ], "meta": { "resourceType": "User" } }
3. Lista de usuarios
- Errores:
- Parámetros de consulta:
- Solicitud de ejemplo:
- Respuesta de ejemplo:
- Solicitud de ejemplo:
- Respuesta de ejemplo:
- Si no se encuentra el usuario con el nombre de usuario, enviamos un esquema vacío indicando que no se encontró ningún usuario.
- Solicitud de ejemplo:
- Respuesta de ejemplo:
- Si el usuario se presenta con el correo electrónico.
- Si el usuario no es encontrado por correo electrónico, el módulo envía un esquema vacío indicando que no se encontró el usuario.
Este punto final permite filtrar y recuperar usuarios específicos de la lista de usuarios existente. Al realizar una solicitud GET a / Usuarios Al añadir parámetros de filtro al punto final, puede refinar los resultados según atributos como el nombre de usuario y el correo electrónico. El punto final admite búsquedas filtradas, pero puede devolver un máximo de 50 registros de usuario por solicitud.
| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| Excepción no encontrada del recurso | El usuario especificado no existe. | 404 |
GET /Usuarios
3.1 StartIndex y recuento
Permite usar startIndex y count como parámetros de consulta. Donde startIndex es el ID de inicio y count es el número máximo de resultados que la consulta puede devolver.
GET /Users?startIndex=1&count=50 Autorización: Portador
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 2, "startIndex": 1, "itemsPerPage": 2, "Resources": [ { "id": "1", "externalId": "1", "meta": { "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "example1@example.com", "displayName": "example1@example.com", "emails": { "value": "example1@example.com", "type": "work", "primary": true }, "active": true, "name": { "familyName": "", "givenName": "" }, "groups": [ "autenticado,administrador" ], "departamento": "" }, { "id": "13", "externalId": "13", "meta": { "resourceType": "Usuario" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Usuario" ], "nombreUsuario": "ejemplo2", "nombreParaMostrar": "ejemplo2", "correosElectrónicos": { "valor": "ejemplo2@ejemplo.com", "tipo": "trabajo", "principal": verdadero }, "activo": verdadero, "nombre": { "apellido": "", "nombreDePila": "" }, "grupos": [ "autenticado,administrador" ], "departamento": "" }, ] }
3.2 Buscar un usuario por su nombre de usuario
GET /Usuarios?filtro=nombreUsuario eq "admin"
Usuario no encontrado - 200 Ok.
{ "esquemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }
Usuario encontrado - 200 Ok.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 10, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid del usuario", "username": "admin", "emails": [ { "value": "email@gmail.com", "primary": true, "type": "work" } ] } ] }
3.3 Buscar al usuario por su dirección de correo electrónico
GET /Users?filter=emails[type eq "work"].value eq "email@gmail.com" Autorización: Portador
Usuario encontrado - 200 Ok.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 10, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid del usuario", "username": "Nombre de usuario", "emails": [ { "value": "email@gmail.com", "primary": true, "type": "work" } ] } ] }
Usuario no encontrado - 200 Ok.
{ "esquemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }
4. Actualización de usuario (PARCHE)
Si el usuario se encuentra en la solicitud GET, se realizará una solicitud PATCH o PUT para actualizarlo; de lo contrario, se realizará una solicitud POST para crearlo. Puede actualizar campos específicos de un usuario mediante un PARCHE solicitud al / Usuarios Punto final. En el cuerpo de la solicitud, incluya el atributo que desea cambiar y su valor actualizado.
PARCHE /Usuarios/{id-usuario}- Errores:
- Solicitud de ejemplo:
- Ejemplo de respuesta: 200 OK.
| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| Excepción no encontrada del recurso | El usuario especificado no existe. | 404 |
PATCH/Usuarios/{{user-id}} HTTP/1.1 Tipo de contenido: aplicación/json Autorización: Portador { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operaciones": [ { "op": "Reemplazar", "path": "emails[type eq \"work\"].value", "value": "email@gmail.com" }, { "op": "Reemplazar", "path": "name.familyName", "value": "familyname" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid del usuario", "userName": "Nombre de usuario", "active": 1, "emails": [ { "primary": true, "value": "email@gmail.com", "type": "work", "display": "email@gmail.com" } ], "meta": { "resourceType": "Usuario" } }
5. Actualizar usuario (PUT)
Puede actualizar un usuario mediante una solicitud PUT a la / Usuarios Punto final. Esta solicitud reemplaza todo el objeto de usuario, por lo que todos los atributos de usuario requeridos deben proporcionarse en el cuerpo.
PUT /Usuarios/{{id-usuario}}- Errores:
- Solicitud de ejemplo:
- Ejemplo de respuesta: 200 ok.
| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| Excepción no encontrada del recurso | El usuario especificado no existe. | 404 |
PUT/Usuarios/{{user-id}} HTTP/1.1 Tipo de contenido: aplicación/json Autorización: Portador { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "97", "userName": "exmple", "active": 1, "emails": [ { "principal": verdadero, "valor": "exmple@example.com", "tipo": "trabajo", "mostrar": "exmple@example.com" } ], "meta": { "resourceType": "Usuario" }, "name": { "givenName": "nombre", "familyName": "apellido", "segundo nombre": "sdf", "honorificPrefix": "sdf" }, "displayName": "nombre familyName", "nickName": "df", "addresses": [ { "principal": verdadero, "localidad": "fdd" } ], "locale": "en-US", "externalId": "9rqltOOLI95d7", "grupos": [] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "97", "userName": "example", "active": 1, "emails": [ { "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" } ], "meta": { "resourceType": "User" } }
6. Crear usuario (POST)
Utilice una solicitud POST en el / Usuarios Punto final para crear un nuevo usuario. Asegúrese de incluir todos los campos necesarios en el cuerpo de la solicitud. Una solicitud exitosa devuelve 201 "Creado" y los detalles del usuario.
POST /Usuarios
- Errores:
- Solicitud de ejemplo:
- Ejemplo de respuesta: 201 creados.
| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| Excepción de conflicto | El usuario ya existe. | 409 |
POST /Usuarios HTTP/1.1 Aceptar: aplicación/json Tipo de contenido: aplicación/json Autorización: Portador { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"], "externalId": "abc", "userName": "example", "active": true, "emails": [{ "primary": true, "type": "work", "value": "example@example.com" }], "meta": { "resourceType": "User" }, "name": { "formatted": "first name last name", "familyName": "last name", "givenName": "first name" } }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "externalId": "abc", "userName": "example", "active": true, "emails": [ { "primary": true, "type": "work", "value": "example@example.com" } ], "meta": { "resourceType": "User" }, "name": { "formatted": "first name last name", "familyName": "last name", "givenName": "first name" }, "id": "98" }
Puntos finales del grupo
1. Grupos de listas
La /Grupos El punto final admite solicitudes GET para recuperar una lista de grupos disponibles en el servidor SCIM. Esta operación devuelve solo la información básica del grupo, como el ID y el nombre para mostrar. La lista de miembros siempre se devuelve vacía, ya que el punto final no incluye los detalles de pertenencia al grupo en la respuesta.
- Solicitud de ejemplo:
- Ejemplo de respuesta: 200 ok
- Filtro compatible:
- Solicitud de ejemplo:
- Ejemplo de respuesta: 200 ok.
GET /Groups HTTP/1.1 Autorización: Portador
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 4, "Resources": [ { "id": "anonymous", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "anonymous" }, { "id": "authenticated", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "authenticated" }, { "id": "administrator", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "administrador" }, { "id": "editor_admin", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "editor_admin" } ], "startIndex": 1, "itemsPerPage": 4 }
GET /Groups?filter=displayName eq "administrador"
GET /scim/Groups?filter=displayName eq "administrador" HTTP/1.1 Autorización: Portador
Si se encuentra un grupo con el nombre para mostrar.
{ "esquemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "Recursos": [], "startIndex": 1, "itemsPerPage": 20 }
2. Buscar grupo por ID
/Grupos/{id} Recupera el recurso de grupo asociado al ID de grupo proporcionado. La respuesta solo devuelve los metadatos del grupo. No se incluyen los datos de membresía.
- Solicitud de ejemplo:
- Respuesta de ejemplo:
GET /Groups/administrator HTTP/1.1 Autorización: Portador
Encontrado - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "administrador", "meta": { "resourceType": "Grupo" }, "displayName": "Administrador" }
No encontrado - 404.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "No se encontró el administrador del grupo", "status": 404 }
3. Crear un grupo
Usar un PUBLICAR solicitud de /Grupos Para crear un nuevo grupo, debe proporcionar un nombre de grupo (displayName). Aunque puede incluir miembros en el cuerpo de la solicitud, la respuesta siempre devolverá una lista vacía de miembros.
- Errores:
- Solicitud de ejemplo:
- Solicitud sin lista de miembros incluida.
- Solicitud con lista de miembros.
- Respuesta: 201 Creado.
| Error | Estado del producto | Código de estado HTTP |
|---|---|---|
| Excepción de validación | O bien el módulo no está activado o se utiliza una clave de licencia incorrecta | 400 |
| Excepción no autorizada | El encabezado de autorización no es válido o falta. | 401 |
| OperaciónNoSoportadaExcepción | No se permite la modificación del grupo. | 501 |
POST /Grupos HTTP/1.1 Autorización: Portador { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "externalId": "id-externo", "displayName": "group2", "meta": { "resourceType": "Group" } }
POST /Grupos HTTP/1.1 Tipo de contenido: aplicación/json Autorización: Portador { "esquemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "nombreParaMostrar": "grupo1", "miembros": [ { "valor": "3", "mostrar": "admin@gmail.com" }, { "valor": "2", "mostrar": "admin2@gmail.com" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "externalId": "id-externo", "displayName": "group2", "meta": { "resourceType": "Group" }, "members": [], "id": "group2" }
4. Actualizar grupo [Atributos de no miembros]
Puede actualizar los detalles básicos de un grupo, como el nombre para mostrar, mediante una solicitud PATCH a /Grupos/{id-del-grupo}Esta solicitud actualiza únicamente los atributos que proporciones y no modifica los miembros del grupo. Una actualización exitosa devuelve el error 204 "Sin contenido".
- Solicitud de ejemplo:
- Ejemplo de respuesta - 204 Sin contenido.
PATCH /Groups/group1 HTTP/1.1 Autorización: Portador{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operaciones": [{ "op": "Reemplazar", "path": "displayName", "value": "updated group1" }] }
5. Actualizar grupo [Miembros]
La /Grupos/{id} El punto final permite agregar y eliminar miembros mediante una solicitud PATCH. El cuerpo de la solicitud debe incluir la lista de ID de usuario que desea agregar. Esta acción solo actualiza los miembros del grupo y devuelve el error 204 "Sin contenido" si se realiza correctamente.
- Solicitud de ejemplo:
- Añade un miembro al grupo.
- Eliminar al miembro del grupo.
- Ejemplo de respuesta- 204 Sin contenido.
PATCH /Grupos/grupo actualizado1 HTTP/1.1 Tipo de contenido: aplicación/json Autorización: Portador { "esquemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operaciones": [{ "op": "Agregar", "ruta": "miembros", "valor": [{ "$ref": null, "valor": "97" }] }] }
PATCH /Grupos/grupo actualizado1 HTTP/1.1 Autorización: Portador { "esquemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operaciones": [{ "op": "Eliminar", "ruta": "miembros", "valor": [{ "$ref": null, "valor": "97" }] }] }
6. Eliminar grupo
La /Grupos/{id} El punto final admite la eliminación de un grupo mediante un BORRAR Solicitud. Esta operación elimina el grupo del servidor SCIM. Una eliminación exitosa devuelve un 204 Sin contenido respuesta, indicando que el grupo fue eliminado y no se proporciona ningún cuerpo de respuesta.
- Solicitud de ejemplo:
- Ejemplo de respuesta - 204 Sin contenido.
ELIMINAR /Grupos/grupo actualizado1 HTTP/1.1 Autorización: Portador
Si la configuración no fue exitosa, por favor contáctenos en drupalsupport@xecurify.com. Envíe la captura de pantalla de la ventana de error y lo ayudaremos a resolver el problema y lo guiaremos a través de la configuración.
