Referencia de API SCIM

URL base

XID expone API SCIM 2.0 con alcance de organización en /scim/v2/organizations/{organization_id}. Los recursos de usuarios y grupos se direccionan con el ID de organización en la ruta.

Configura tu proveedor de identidad con la URL base https://xid.dev/scim/v2/organizations/{organization_id} y el token de directorio que se muestra una sola vez cuando creas o rotas el directorio.

curl https://xid.dev/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'

Autenticación

Las llamadas SCIM usan un token bearer de directorio creado desde la API de administración. XID almacena solo un hash del token y devuelve el token en texto claro una sola vez cuando se crea o se rota.

Puntos de conexión

Recurso de usuario

Los recursos de usuario usan userName como identificador externo. Los valores de correo, campos de nombre del perfil, estado activo y campos de extensión empresarial se conservan en el perfil SCIM bruto.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}

Recurso de grupo

Los recursos de grupo usan displayName como nombre único de grupo de directorio. Los miembros referencian IDs de usuario SCIM y se sincronizan de forma idempotente.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "dir_user_123", "display": "alice@example.com" }
  ]
}

Filtrado, ordenación y paginación

XID admite gramática de filtro SCIM con and, or, not y operadores de comparación (eq, ne, co, sw, ew, gt, ge, lt, le, pr). Las expresiones no soportadas devuelven invalidFilter. Las listas usan paginación SCIM base 1 con startIndex, count, totalResults, más sortBy y sortOrder opcionales.

Operaciones masivas

POST /scim/v2/organizations/{organization_id}/Bulk acepta una BulkRequest con hasta 100 operaciones y límite de 1 MiB. Las respuestas devuelven el estado HTTP por operación en una BulkResponse aunque algunas fallen.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": { "userName": "alice@example.com", "active": true }
    }
  ]
}

ETag and If-Match

Las respuestas GET de recursos incluyen ETag: W/"<meta.version>" de meta.version. PUT y PATCH requieren encabezado If-Match con la versión actual; ausente → 428, desajuste → 412.

Operaciones PATCH

Las solicitudes PATCH usan urn:ietf:params:scim:api:messages:2.0:PatchOp. XID admite add, replace y remove para campos de perfil editables y membresías de grupo.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

Respuestas de error

Los errores SCIM devuelven application/scim+json con el esquema SCIM Error, estado HTTP, detalle y scimType opcional.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "userName already exists"
}

Capacidades de ServiceProviderConfig

• ServiceProviderConfig anuncia sort.supported=true, bulk.supported=true y etag.supported=true.
• XID expone endpoints inbound de SCIM Service Provider para IdP externos. Los clientes de push SCIM para SaaS downstream tienen evidencia local con un SaaS simulado, pero la compatibilidad con producción aún requiere una L4 real de administración de SaaS.

Comportamiento de desaprovisionamiento

• La rotación del token de directorio mantiene válido el token anterior durante una breve ventana de gracia.
• active=false y DELETE /Users/{id} desaprovisionar al usuario y revocar sesiones activas.
• Las actualizaciones de membresía de grupo son idempotentes. Los miembros desconocidos se pueden resolver después de que el usuario llegue desde el proveedor de identidad.