API de Aprovisionamiento SCIM 2.0

Auris implementa el protocolo SCIM 2.0 (System for Cross-domain Identity Management) para el aprovisionamiento automatizado de usuarios y grupos. SCIM permite que proveedores de identidad como Okta, Azure AD (Entra ID), OneLogin y JumpCloud creen, actualicen y desactiven automáticamente cuentas de usuario en Auris cuando se realizan cambios en el directorio del IdP.

La API SCIM sigue las especificaciones RFC 7643 (Core Schema) y RFC 7644 (Protocol).

Configuración de la Conexión SCIM

Antes de que tu IdP pueda aprovisionar usuarios, debes crear una conexión SCIM en la Consola de Auris:

Ve a Consola > Configuración > Aprovisionamiento SCIM
Haz clic en Agregar Conexión
Anota la URL Base SCIM y el Bearer Token
Configura estos datos en los ajustes de integración SCIM de tu IdP

La URL base SCIM sigue este formato:


https://api.altovar.net/api/scim/v2

Autenticación

Todos los endpoints SCIM usan autenticación con Bearer token. El token se genera al crear una conexión SCIM en la Consola de Auris.


Authorization: Bearer scim_token_here

El token autentica al IdP e identifica qué configuración de conexión SCIM usar (incluyendo el realm de Keycloak de destino y los mapeos de atributos).

Los tokens SCIM son de larga duración y otorgan acceso completo de aprovisionamiento. Trátalos como secretos. Rota los tokens periódicamente a través de la Consola de Auris.

Gestión de Conexiones

Estos endpoints son para gestionar conexiones SCIM desde la Consola de Auris (API de administración). No forman parte del protocolo SCIM en sí.

GET/api/scim/connectionsRequires: view:scim_connections

Lista todas las conexiones SCIM del tenant.

Respuesta exitosa


{
  "ok": true,
  "data": [
    {
      "id": "scim_conn_abc123",
      "name": "Okta Production",
      "provider": "okta",
      "keycloakRealm": "acme-corp",
      "isActive": true,
      "lastSyncAt": "2025-02-18T09:00:00Z",
      "userCount": 245,
      "groupCount": 12,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

POST/api/scim/connectionsRequires: manage:scim_connections

Crea una nueva conexión SCIM. Devuelve los detalles de la conexión incluyendo el Bearer token generado. El token solo se devuelve una vez — guárdalo de forma segura.

Cuerpo de la solicitud


{
  "name": "Okta Production",
  "provider": "okta",
  "keycloakRealm": "acme-corp"
}

Success response


{
  "ok": true,
  "data": {
    "id": "scim_conn_def456",
    "name": "Okta Production",
    "provider": "okta",
    "keycloakRealm": "acme-corp",
    "token": "scim_abc123def456...",
    "baseUrl": "https://api.altovar.net/api/scim/v2",
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Usuarios

Listar Usuarios

GET/api/scim/v2/UsersRequires: SCIM Bearer token

Lista los usuarios del tenant. Admite filtrado SCIM, paginación y selección de atributos. Devuelve los usuarios en formato SCIM Core Schema.

Parámetros de consulta

Parámetro	Tipo	Descripción
`filter`	string	Expresión de filtro SCIM (ver Sintaxis de Filtros)
`startIndex`	integer	Índice de inicio basado en 1 (por defecto: 1)
`count`	integer	Resultados máximos por página (por defecto: 20, máx.: 100)
`sortBy`	string	Atributo por el que ordenar (p. ej., `userName`)
`sortOrder`	`ascending` \| `descending`	Dirección de ordenamiento (por defecto: `ascending`)
`attributes`	string	Lista de atributos a incluir separados por comas
`excludedAttributes`	string	Lista de atributos a excluir separados por comas

Ejemplo de solicitud


GET /api/scim/v2/Users?filter=userName eq "[email protected]"&count=10

Respuesta exitosa


{
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "usr_abc123",
      "externalId": "okta_user_001",
      "userName": "[email protected]",
      "name": {
        "givenName": "Alice",
        "familyName": "Smith",
        "formatted": "Alice Smith"
      },
      "displayName": "Alice Smith",
      "emails": [
        {
          "value": "[email protected]",
          "type": "work",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "+39021234567",
          "type": "work"
        }
      ],
      "active": true,
      "groups": [
        {
          "value": "group_eng",
          "display": "Engineering"
        }
      ],
      "meta": {
        "resourceType": "User",
        "created": "2025-01-15T10:00:00Z",
        "lastModified": "2025-02-18T09:00:00Z",
        "location": "https://api.altovar.net/api/scim/v2/Users/usr_abc123"
      }
    }
  ]
}

Las respuestas SCIM usan el formato de esquema SCIM (no el sobre estándar de la API de Auris). Los campos schemas, el array Resources y el objeto meta son requeridos por la especificación SCIM.

Obtener Usuario

GET/api/scim/v2/Users/[id]Requires: SCIM Bearer token

Recupera un único usuario por su ID de usuario de Auris. Devuelve la representación SCIM completa del usuario.

Respuesta exitosa


{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "usr_abc123",
  "externalId": "okta_user_001",
  "userName": "[email protected]",
  "name": {
    "givenName": "Alice",
    "familyName": "Smith",
    "formatted": "Alice Smith"
  },
  "displayName": "Alice Smith",
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "groups": [
    {
      "value": "group_eng",
      "display": "Engineering"
    }
  ],
  "meta": {
    "resourceType": "User",
    "created": "2025-01-15T10:00:00Z",
    "lastModified": "2025-02-18T09:00:00Z",
    "location": "https://api.altovar.net/api/scim/v2/Users/usr_abc123"
  }
}

Respuesta de error (formato SCIM)


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "User not found",
  "status": "404"
}

Crear Usuario

POST/api/scim/v2/UsersRequires: SCIM Bearer token

Crea una nueva cuenta de usuario. El usuario se crea tanto en la base de datos de Auris como en el realm de Keycloak asociado a la conexión SCIM. Si se proporciona externalId, se almacena para futura reconciliación.

Cuerpo de la solicitud


{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId": "okta_user_002",
  "userName": "[email protected]",
  "name": {
    "givenName": "Bob",
    "familyName": "Jones"
  },
  "displayName": "Bob Jones",
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true
}

Mapeo de campos SCIM a Auris (por defecto)

Campo SCIM	Campo Auris	Notas
`userName`	`email` / `scimUserName`	Usado como identificador principal
`externalId`	`scimExternalId`	Identificador único del lado del IdP
`name.givenName`	`firstName`
`name.familyName`	`lastName`
`displayName`	Calculado	`firstName + " " + lastName`
`emails[primary].value`	`email`	El email principal se convierte en el email de Auris
`phoneNumbers[0].value`	`phoneNumber`
`active`	`enabled`

Respuesta exitosa (HTTP 201)


{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "usr_new789",
  "externalId": "okta_user_002",
  "userName": "[email protected]",
  "name": {
    "givenName": "Bob",
    "familyName": "Jones",
    "formatted": "Bob Jones"
  },
  "displayName": "Bob Jones",
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2025-02-18T10:00:00Z",
    "lastModified": "2025-02-18T10:00:00Z",
    "location": "https://api.altovar.net/api/scim/v2/Users/usr_new789"
  }
}

Respuesta de error


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

Reemplazar Usuario (Actualización Completa)

PUT/api/scim/v2/Users/[id]Requires: SCIM Bearer token

Reemplaza completamente un recurso de usuario. Todos los atributos SCIM del cuerpo de la solicitud reemplazan los valores actuales. Los atributos no presentes en el cuerpo de la solicitud se borran (se establecen como null/vacío).

Cuerpo de la solicitud


{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId": "okta_user_001",
  "userName": "[email protected]",
  "name": {
    "givenName": "Alicia",
    "familyName": "Smith-Jones"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true
}

Respuesta exitosa: Representación SCIM completa del usuario (mismo formato que GET).

Actualización Parcial (PATCH)

PATCH/api/scim/v2/Users/[id]Requires: SCIM Bearer token

Actualiza parcialmente un usuario usando operaciones SCIM PATCH. Este es el método de actualización más comúnmente usado por los IdPs. Admite operaciones add, replace y remove.

Cuerpo de la solicitud — Desactivar usuario


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

Cuerpo de la solicitud — Actualizar múltiples campos


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "Smith-Jones"
    },
    {
      "op": "replace",
      "path": "emails[type eq \"work\"].value",
      "value": "[email protected]"
    }
  ]
}

Tipos de operación PATCH

Operación	Descripción
`add`	Agrega un nuevo valor a un atributo multivaluado o establece un atributo de valor único
`replace`	Reemplaza el valor actual de un atributo
`remove`	Elimina un valor de atributo

Respuesta exitosa: Representación SCIM completa del usuario reflejando el estado actualizado.

Eliminar Usuario

DELETE/api/scim/v2/Users/[id]Requires: SCIM Bearer token

Elimina (desactiva) un usuario. En Auris, la eliminación SCIM realiza una eliminación suave: el usuario es deshabilitado y su cuenta de Keycloak es eliminada, pero el registro en la base de datos se conserva con fines de auditoría.

Respuesta exitosa: HTTP 204 No Content (cuerpo vacío, según la especificación SCIM).

Grupos

Listar Grupos

GET/api/scim/v2/GroupsRequires: SCIM Bearer token

Lista los grupos del tenant. Los grupos en Auris corresponden a roles. Admite filtrado SCIM y paginación.

Parámetros de consulta

Parámetro	Tipo	Descripción
`filter`	string	Expresión de filtro SCIM
`startIndex`	integer	Índice de inicio basado en 1 (por defecto: 1)
`count`	integer	Resultados máximos por página (por defecto: 20)

Respuesta exitosa


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "role_abc123",
      "displayName": "engineering",
      "members": [
        {
          "value": "usr_abc123",
          "display": "[email protected]"
        },
        {
          "value": "usr_def456",
          "display": "[email protected]"
        }
      ],
      "meta": {
        "resourceType": "Group",
        "created": "2025-01-01T00:00:00Z",
        "lastModified": "2025-02-15T10:00:00Z",
        "location": "https://api.altovar.net/api/scim/v2/Groups/role_abc123"
      }
    }
  ]
}

Obtener Grupo

GET/api/scim/v2/Groups/[id]Requires: SCIM Bearer token

Recupera un único grupo por ID, incluyendo su lista de miembros.

Crear Grupo

POST/api/scim/v2/GroupsRequires: SCIM Bearer token

Crea un nuevo grupo (rol) con miembros iniciales opcionales.

Cuerpo de la solicitud


{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "marketing",
  "members": [
    {
      "value": "usr_abc123"
    }
  ]
}

Respuesta exitosa (HTTP 201): Representación SCIM completa del grupo.

Reemplazar Grupo

PUT/api/scim/v2/Groups/[id]Requires: SCIM Bearer token

Reemplaza completamente un recurso de grupo. La lista de miembros en la solicitud reemplaza a los miembros actuales.

Actualización Parcial de Grupo

PATCH/api/scim/v2/Groups/[id]Requires: SCIM Bearer token

Actualiza parcialmente un grupo usando operaciones SCIM PATCH. Se usa principalmente para agregar o eliminar miembros.

Cuerpo de la solicitud — Agregar miembros


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "usr_ghi789" },
        { "value": "usr_jkl012" }
      ]
    }
  ]
}

Cuerpo de la solicitud — Eliminar un miembro


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"usr_abc123\"]"
    }
  ]
}

Eliminar Grupo

DELETE/api/scim/v2/Groups/[id]Requires: SCIM Bearer token

Elimina un grupo (rol). Todos los miembros son desasignados. Devuelve HTTP 204 No Content.

Operaciones en Masa

POST/api/scim/v2/BulkRequires: SCIM Bearer token

Ejecuta múltiples operaciones SCIM en una única solicitud. Admite hasta 100 operaciones por solicitud. Cada operación se procesa de forma independiente — un fallo en una operación no impide que las demás se ejecuten. Conforme a RFC 7644 Sección 3.7.

Cuerpo de la solicitud


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "userName": "[email protected]",
        "name": {
          "givenName": "Charlie",
          "familyName": "Brown"
        },
        "emails": [{ "value": "[email protected]", "primary": true }],
        "active": true
      }
    },
    {
      "method": "PATCH",
      "path": "/Users/usr_abc123",
      "data": {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
          { "op": "replace", "path": "active", "value": false }
        ]
      }
    },
    {
      "method": "DELETE",
      "path": "/Users/usr_old999"
    }
  ]
}

Respuesta exitosa


{
  "Operations": [
    {
      "method": "POST",
      "bulkId": "user1",
      "status": "201",
      "location": "https://api.altovar.net/api/scim/v2/Users/usr_new123",
      "response": {
        "id": "usr_new123",
        "userName": "[email protected]"
      }
    },
    {
      "method": "PATCH",
      "location": "https://api.altovar.net/api/scim/v2/Users/usr_abc123",
      "status": "200"
    },
    {
      "method": "DELETE",
      "location": "https://api.altovar.net/api/scim/v2/Users/usr_old999",
      "status": "204"
    }
  ]
}

Ejemplo de operación fallida


{
  "method": "POST",
  "bulkId": "user2",
  "status": "409",
  "response": {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
    "detail": "User with userName '[email protected]' already exists",
    "scimType": "uniqueness"
  }
}

Límites

Límite	Valor
Operaciones máximas por solicitud	100
Métodos admitidos	`POST`, `PUT`, `PATCH`, `DELETE`
`GET` en bulk	No admitido (usa los endpoints de listado en su lugar)

Las operaciones en masa no son transaccionales. Cada operación se procesa de forma independiente. Si la operación #3 falla, las operaciones #1, #2, #4, etc. siguen procesándose. Verifica el campo status de cada operación en la respuesta.

Sintaxis de Filtros

La sintaxis de filtros SCIM (RFC 7644 Sección 3.4.2.2) admite comparación de atributos, operadores lógicos y agrupación. Auris implementa un analizador de descenso recursivo que maneja la gramática completa de filtros.

Operadores de Comparación

Operador	Descripción	Ejemplo
`eq`	Igual	`userName eq "[email protected]"`
`ne`	Distinto	`active ne false`
`co`	Contiene (subcadena)	`name.familyName co "smith"`
`sw`	Empieza por	`userName sw "alice"`
`ew`	Termina en	`userName ew "@example.com"`
`gt`	Mayor que	`meta.lastModified gt "2025-01-01T00:00:00Z"`
`lt`	Menor que	`meta.created lt "2025-02-01T00:00:00Z"`
`ge`	Mayor o igual que	`meta.lastModified ge "2025-01-01T00:00:00Z"`
`le`	Menor o igual que	`meta.created le "2025-02-01T00:00:00Z"`
`pr`	Presente (el atributo existe y no está vacío)	`phoneNumbers pr`

Operadores Lógicos

Operador	Descripción	Ejemplo
`and`	Ambas condiciones deben ser verdaderas	`active eq true and name.familyName co "smith"`
`or`	Al menos una condición debe ser verdadera	`userName eq "[email protected]" or userName eq "[email protected]"`

Agrupación

Usa paréntesis para controlar el orden de evaluación:


(active eq true) and (name.familyName eq "Smith" or name.familyName eq "Jones")

Rutas de Atributos con Notación de Punto

Los atributos anidados usan notación de punto:


name.givenName eq "Alice"
emails[type eq "work"].value sw "alice"

Ejemplos de Filtros

Buscar un usuario por email:


GET /api/scim/v2/Users?filter=userName eq "[email protected]"

Buscar todos los usuarios activos con un apellido específico:


GET /api/scim/v2/Users?filter=active eq true and name.familyName eq "Smith"

Buscar usuarios modificados después de una fecha específica:


GET /api/scim/v2/Users?filter=meta.lastModified gt "2025-02-01T00:00:00Z"

Buscar usuarios con número de teléfono:


GET /api/scim/v2/Users?filter=phoneNumbers pr

Mapeo de Atributos

Auris admite mapeo personalizado de atributos entre los atributos SCIM y los campos de usuario de Auris. Los mapeos se pueden configurar por conexión SCIM a través de la Consola o la API.

GET/api/scim/connections/[id]/mappingsRequires: manage:scim_connections

Lista los mapeos de atributos para una conexión SCIM.

Respuesta exitosa


{
  "ok": true,
  "data": [
    {
      "id": "map_abc123",
      "scimAttribute": "userName",
      "aurisAttribute": "email",
      "direction": "both",
      "isActive": true
    },
    {
      "id": "map_def456",
      "scimAttribute": "name.givenName",
      "aurisAttribute": "firstName",
      "direction": "both",
      "isActive": true
    },
    {
      "id": "map_ghi789",
      "scimAttribute": "urn:custom:department",
      "aurisAttribute": "metadata.department",
      "direction": "inbound",
      "isActive": true
    }
  ]
}

Direcciones de mapeo

Dirección	Descripción
`inbound`	Solo del IdP a Auris (usado durante el aprovisionamiento desde el IdP)
`outbound`	Solo de Auris al IdP (usado cuando el IdP lee de Auris)
`both`	Mapeo bidireccional

POST/api/scim/connections/[id]/mappingsRequires: manage:scim_connections

Crea un nuevo mapeo de atributos.

Cuerpo de la solicitud


{
  "scimAttribute": "urn:custom:department",
  "aurisAttribute": "metadata.department",
  "direction": "inbound"
}

DELETE/api/scim/connections/[id]/mappings/[mappingId]Requires: manage:scim_connections

Elimina un mapeo de atributos.

Estadísticas de Sincronización

GET/api/scim/connections/[id]/statsRequires: view:scim_connections

Obtiene estadísticas de aprovisionamiento para una conexión SCIM, desglosadas por período de tiempo.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "last24Hours": {
      "created": 5,
      "updated": 12,
      "deactivated": 1,
      "errors": 0
    },
    "last7Days": {
      "created": 23,
      "updated": 89,
      "deactivated": 4,
      "errors": 2
    },
    "last30Days": {
      "created": 67,
      "updated": 312,
      "deactivated": 11,
      "errors": 5
    }
  }
}

Prueba de Conexión

POST/api/scim/connections/[id]/testRequires: manage:scim_connections

Prueba una conexión SCIM realizando una verificación de estado. Verifica que el Bearer token sea válido, que el realm de Keycloak sea accesible y que la conexión pueda listar usuarios.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "success": true,
    "tokenValid": true,
    "realmAccessible": true,
    "userCount": 245,
    "latency": 89
  }
}

Respuesta de prueba fallida


{
  "ok": true,
  "data": {
    "success": false,
    "tokenValid": true,
    "realmAccessible": false,
    "error": "Keycloak realm 'acme-corp' is not reachable"
  }
}

Formato de Errores SCIM

Los errores SCIM siguen el esquema de error de RFC 7644:


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "Descripción legible del error",
  "status": "400",
  "scimType": "invalidValue"
}

Tipos de error SCIM

scimType	HTTP Status	Descripción
`invalidValue`	400	La solicitud contiene un valor de atributo inválido
`invalidFilter`	400	La expresión de filtro tiene un error de sintaxis
`tooMany`	400	La solicitud bulk supera el conteo máximo de operaciones
`uniqueness`	409	El valor de atributo viola una restricción de unicidad (p. ej., email duplicado)
`mutability`	400	Se intentó modificar un atributo de solo lectura
(none)	401	Bearer token inválido o faltante
(none)	404	Recurso no encontrado

Notas Específicas por IdP

Okta

Okta envía userName como el email del usuario por defecto. La aplicación SCIM de Okta admite:

Aprovisionamiento de usuarios (crear, actualizar, desactivar)
Sincronización de grupos (asignar grupos de Okta a roles de Auris)
Sincronización de perfil (mapeo de atributos en el administrador de Okta)

Establece la URL base del conector SCIM como https://api.altovar.net/api/scim/v2 y la autenticación como HTTP Header con el Bearer token.

Azure AD (Entra ID)

Azure AD usa externalId como clave de reconciliación principal. Configura:

Modo de aprovisionamiento: Automático
URL del tenant: https://api.altovar.net/api/scim/v2
Token secreto: Tu Bearer token SCIM
Mapeo: Mapea userPrincipalName a userName

Azure AD envía solicitudes PATCH con un formato ligeramente no estándar para los atributos multivaluados. Auris maneja estas variaciones automáticamente.

OneLogin

OneLogin admite aprovisionamiento SCIM 2.0. Configura la URL Base SCIM y el Bearer token en la configuración de aprovisionamiento de la aplicación de OneLogin. OneLogin usa externalId para la reconciliación de usuarios.

Referencia de Permisos

Permiso	Descripción
`manage:scim_connections`	Crear, actualizar y eliminar conexiones SCIM y mapeos de atributos
`view:scim_connections`	Ver conexiones SCIM y estadísticas de sincronización
`view:scim_logs`	Ver registros de aprovisionamiento SCIM

Los endpoints del protocolo SCIM (/api/scim/v2/*) usan autenticación con Bearer token de la conexión SCIM, no los permisos de administración estándar de Auris. Los permisos listados arriba aplican solo a los endpoints de gestión de conexiones en la Consola de Auris.

Relacionado

Protocolo SCIM 2.0 — Cómo funciona el aprovisionamiento SCIM a nivel de protocolo
Aprovisionamiento SCIM 2.0 — Guía de configuración SCIM paso a paso
Aprovisionamiento SCIM — Configura conexiones SCIM desde la Consola
API de Usuarios — Endpoints de gestión manual de usuarios
API de Importación y Exportación de Usuarios — Alternativa de migración masiva de usuarios