Aprovisionamiento SCIM

Probara sirve SCIM 2.0 (RFC 7643 y RFC 7644) en https://app.probara.net/scim/v2. Un proveedor de identidad lo usa para crear, actualizar, desactivar y eliminar a las personas de una organización, y para enviar los grupos de esa organización. Esta página es la referencia del endpoint. Para conectar un proveedor desde la app, lee la guía de aprovisionamiento SCIM.

SCIM es una función del plan Enterprise. En cualquier otro plan, cada petición con un token válido responde 403 con el detalle SCIM requires the Enterprise plan.

Ruta rápida

1. Crea un token en la página SCIM del espacio de trabajo y copia su secreto. Probara lo muestra una sola vez.
2. Envía Authorization: Bearer <token> en cada petición a https://app.probara.net/scim/v2.
3. Comprueba la conexión con GET /ServiceProviderConfig, que responde 200 con application/scim+json, y con GET /Users?count=1.

URL base y autenticación

Tema	Comportamiento
URL base	https://app.probara.net/scim/v2, la misma para todas las organizaciones. Solo el token decide la organización. No se lee ningún identificador de organización de la URL ni de una cabecera.
Token	Empieza por probara_scim_, seguido de 43 caracteres base64url. Se crea en la página SCIM del espacio de trabajo, se muestra una vez y vale como máximo 365 días. Una organización tiene como máximo dos tokens activos.
Cabecera	Authorization: Bearer <token>. Cualquier otro esquema se rechaza.
Alcance	Un token SCIM solo funciona en /scim/v2. /api/v1 lo rechaza.
Rechazo	401 con WWW-Authenticate: Bearer. El detalle es el mismo si el token falta, es desconocido, está revocado o ha caducado, así que nunca indica qué comprobación falló.
Estado de la organización	Mientras una organización está suspendida o programada para eliminación, cada escritura responde 403. Las lecturas siguen abiertas.

Endpoints

Método y ruta	Respuesta
GET /ServiceProviderConfig	Capacidades. Patch y filtros están soportados, con hasta 100 resultados por página. Bulk, cambio de contraseña, orden y ETag no lo están.
GET /ResourceTypes, GET /ResourceTypes/{id}	Los tipos de recurso User y Group. Cualquier otro id responde 404.
GET /Schemas, GET /Schemas/{urn}	El esquema User, sus extensiones enterprise y de Probara, y el esquema Group. Cualquier otro URN responde 404.
GET /Users, POST /Users	Listar o crear personas. Una creación responde 201 con cabecera Location.
GET /Users/{id}, PUT /Users/{id}, PATCH /Users/{id}	Leer, reemplazar o parchear una persona.
DELETE /Users/{id}	Quita la membresía de la persona, si tiene una, y después el registro SCIM. Responde 204 sin cuerpo.
GET /Groups, POST /Groups	Listar o crear grupos. Una creación responde 201 con cabecera Location.
GET /Groups/{id}, PUT /Groups/{id}, PATCH /Groups/{id}	Leer, reemplazar o parchear un grupo.
DELETE /Groups/{id}	Elimina el grupo y sus accesos. Responde 204 sin cuerpo.
/Bulk, /Me, /.search	Responden 501.

Una barra final nombra la misma ruta. Un método que la ruta no acepta responde 405 con una cabecera Allow que lista los métodos aceptados. Cualquier otra ruta responde 404.

Filtros

Recurso	Filtro	Coincidencia
Usuarios	userName eq "…"	Sin distinguir mayúsculas
Usuarios	externalId eq "…"	Exacta
Usuarios	emails[type eq "work"].value eq "…"	Sin distinguir mayúsculas
Grupos	displayName eq "…"	Sin distinguir mayúsculas
Grupos	externalId eq "…"	Exacta

Las condiciones se unen con and. Los nombres de atributo y eq no distinguen mayúsculas. Dentro de un valor, \" representa una comilla y \\ una barra invertida. Cualquier otro filtro responde 400 con scimType invalidFilter. Un filtro sin coincidencias responde 200 con totalResults en 0 y un arreglo Resources vacío, nunca 404.

Paginación y atributos

Parámetro	Comportamiento
startIndex	Empieza en 1. Un valor menor que 1 cuenta como 1. Un valor que no es un número entero responde 400 con scimType invalidValue.
count	Hasta 100, y 100 si se omite. Un valor mayor cuenta como 100, y uno negativo como 0. Un valor que no es un número entero responde 400 con scimType invalidValue.
Orden	Del más antiguo al más reciente, por fecha de creación y después por id. El orden es el mismo en todas las páginas.
attributes	Devuelve solo los atributos indicados.
excludedAttributes	Quita los atributos indicados. Probara admite excludedAttributes=members en los grupos.

schemas, id y meta siempre se devuelven. Un URN con un subatributo, como urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department, selecciona solo ese subatributo. totalResults cuenta todas las coincidencias, e itemsPerPage cuenta los recursos de la página.

Usuarios

Atributos

Atributo	Comportamiento
userName	Obligatorio al crear y al reemplazar. Único por organización, con comparación sin distinguir mayúsculas.
emails (tipo work)	La dirección de trabajo, que debe ser una dirección de correo. Si no hay dirección de trabajo, userName debe ser una dirección de correo y sirve como dirección.
active	Un booleano, o la cadena "True" o "False" en cualquier combinación de mayúsculas. Vale true por defecto al crear.
externalId, displayName, title, name.givenName, name.familyName, name.formatted	Se guardan por organización. El perfil global de la persona nunca cambia.
department y employeeNumber de la extensión enterprise	Se guardan por organización.
role de Probara y roles de Entra	Valores de rol. Consulta Roles.
password	Se ignora. Probara no sincroniza contraseñas.
groups	Se ignora en el cuerpo de un usuario. La pertenencia a grupos se envía por /Groups.

Crear y reemplazar

POST y PUT reciben a la persona completa. PUT borra cada atributo que el cuerpo omite.

Un POST para una dirección que ya es miembro de la organización adopta esa membresía en el nuevo registro, así que nadie se añade dos veces. Un POST cuyo userName o dirección de trabajo ya pertenece a otro registro de la organización responde 409 con scimType uniqueness.

Una persona de uno de los dominios verificados de la organización recibe una cuenta y una membresía en el mismo cambio, con el rol que indica Roles. Una persona de fuera de esos dominios recibe una invitación, y su registro queda sin cuenta hasta que la acepte.

Patch

PATCH recibe un arreglo Operations. op es add, replace o remove, en cualquier combinación de mayúsculas. Las operaciones se aplican en orden, y una sola operación rechazada rechaza la petición entera.

Ruta	Comportamiento
active	Cambia el estado. La desactivación y la reactivación se describen más abajo.
userName, externalId, displayName, title, name.givenName, name.familyName, name.formatted	Asignan el valor. remove lo borra, salvo userName, que responde 400 con scimType invalidValue.
emails[type eq "work"].value, emails	Asignan la dirección de trabajo.
department, employeeNumber y sus formas URN de extensión	Asignan el valor.
Las rutas de rol descritas en Roles	Asignan el rol.
emails[type eq "home"], password, groups	Se ignoran.
Cualquier otra ruta	Responde 400 con scimType invalidPath.

Un replace sin path recibe un objeto de atributos, la forma de Okta. Sus claves se leen como rutas de atributo. Si el objeto incluye el propio recurso, se omiten su id, schemas y meta, que no cambian nada, tanto en usuarios como en grupos.

Cambios de dirección

La dirección de una persona es su correo de trabajo, o userName cuando no hay correo de trabajo. Solo se permite cambiarla si la dirección anterior y la nueva están en dominios verificados de la organización y la cuenta no pertenece a ninguna otra organización. Si no, la respuesta es 400 con scimType mutability y un motivo. Un cambio solo de userName, mientras un correo de trabajo sostiene la dirección, cambia únicamente la etiqueta.

Desactivación, reactivación y eliminación

Cambio	Efecto
active a false (PATCH o PUT)	La membresía se conserva, desactivada: la siguiente petición de la persona a la organización se rechaza, y el puesto queda libre. Su rol, su acceso a proyectos y sus grupos se conservan. Terminan las sesiones creadas mediante la conexión de inicio de sesión único de la organización. Se revocan los tokens API personales y los permisos OAuth y MCP de la organización. Las asignaciones abiertas de ejecuciones y las solicitudes de revisión pendientes quedan sin asignar. El registro SCIM se conserva, inactivo, y sigue apareciendo en GET y en los filtros.
active a true	Vuelve el mismo id. La membresía vuelve a estar activa con su rol, el que den sus grupos, su atributo o el rol por defecto, tras una comprobación de puesto. Con Gestionado en Probara el rol se conserva. Sus grupos recordados se restauran. Los tokens y permisos revocados no se restauran.
DELETE	Se quita la membresía: el puesto queda libre, el acceso de la persona termina, y sus grupos y su trabajo abierto salen con ella. Después se elimina el registro SCIM. La cuenta se conserva. Después, el id responde 404.

En todos los casos la cuenta se conserva. Los tokens de aplicación de CI de la organización no se ven afectados. Los casos, suites, ejecuciones, resultados, defectos, comentarios y revisiones que creó la persona se conservan y siguen asociados a ella.

El propietario de una organización no puede ser desaprovisionado. Una desactivación o un DELETE del propietario responde 400 con el detalle The organization owner can't be deprovisioned by SCIM. Transfer ownership first. y no escribe nada.

Grupos

Cada grupo que envía el proveedor de identidad se convierte en un grupo de usuarios de Probara que gestiona ese proveedor.

• Nombre y miembros los envía el proveedor de identidad. En Probara, la descripción del grupo y sus permisos de proyecto, de paneles y de consultas guardadas siguen siendo editables. Renombrar, eliminar o cambiar los miembros del grupo en Probara responde 409.
• Miembros se aplican solo cuando tienen una cuenta vinculada y están activos en la organización. Los demás quedan recordados, y se unen al grupo de Probara cuando se activan.
• Choques de nombre. Un nombre de grupo que coincide con un grupo creado en Probara, sin distinguir mayúsculas, responde 409 con scimType uniqueness. No se escribe nada.
• PUT reemplaza el nombre, el externalId y la lista completa de miembros.
• PATCH con add o remove cambia solo a las personas que nombra. Un replace sobre members fija la lista completa. Quitar a alguien que no es miembro no hace nada.

Operación con miembros	Forma
Quitar un miembro	remove con la ruta members[value eq "<id>"]
Quitar varios miembros	remove con la ruta members y un arreglo de objetos {"value": "<id>"}
Quitar todos los miembros	remove con la ruta members y sin valor
Reemplazar la lista	replace con la ruta members y un arreglo de valores

Un valor de miembro que no es un id de Users de esta organización responde 400 con scimType invalidValue.

DELETE elimina el grupo de Probara y sus permisos de proyecto, de paneles y de consultas guardadas. La asignación de roles a los grupos no forma parte de este recurso: se configura en los ajustes SCIM del espacio de trabajo.

Roles

La fuente de roles de la organización decide qué datos del proveedor de identidad fijan el rol de una persona.

Fuente de roles	El rol viene de	Cuando una persona no tiene valor
groups (por defecto)	El grupo asignado con el número de prioridad más bajo. Entre los grupos que comparten ese número, gana el rol que concede más permisos.	El rol por defecto de la organización
attribute	El valor role de la extensión de Probara, o los valores roles de Entra. Varios valores resuelven al rol que concede más permisos, y un empate va al slug menor.	El rol por defecto de la organización
probara	Nada. SCIM fija el rol al aprovisionar a la persona, y las actualizaciones posteriores no lo cambian.	No aplica

El rol por defecto es el que la política de inicio de sesión único de la organización da a los nuevos miembros. Es Lector hasta que lo cambies.

Formas de rol

Con la fuente attribute, un rol llega en una de estas formas, en POST, PUT y PATCH:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:probara:2.0:User"
  ],
  "userName": "ada@example.com",
  "urn:ietf:params:scim:schemas:extension:probara:2.0:User": { "role": "member" }
}

{ "roles": [{ "value": "member" }] }

Entra también puede enviar roles como un objeto de rol de aplicación codificado en JSON, como una cadena JSON del arreglo, o como una cadena simple. Cada forma resuelve al value de rol que contiene.

Regla	Comportamiento
Valor	Un slug de rol de la organización: admin, member, viewer, o el identificador de un rol personalizado.
owner	Nunca se asigna. Con attribute responde 400 con scimType invalidValue.
Slug desconocido	Con attribute responde 400 con scimType invalidValue.
Otras fuentes	Con groups y probara, un valor de rol no cambia ningún rol y nunca rechaza la petición.

En PATCH, la ruta de Probara es urn:ietf:params:scim:schemas:extension:probara:2.0:User:role, y roles es la ruta de Entra. add añade al rol guardado, remove lo borra y replace lo fija. Un filtro de valor sobre roles responde 400 con scimType invalidPath.

Errores

Cada error usa el esquema de error SCIM, con status como cadena:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "A user with this userName already exists in this organization."
}

Los textos detail se devuelven en inglés, tal como los produce la API. Compáralos sin traducir. El detail está escrito para el administrador, y un proveedor de identidad puede mostrarlo en su registro. scimType aparece solo donde la tabla lo indica.

Estado	Cuándo	scimType
400	Un cuerpo, filtro, ruta o valor mal formado, una negativa por ser propietario, o un cambio de dirección rechazado	invalidSyntax, invalidFilter, invalidPath, invalidValue, noTarget o mutability, cuando la tabla lo indica
401	Un token ausente, desconocido, revocado o caducado	Ninguno
403	Falta el plan Enterprise, la organización está suspendida o programada para eliminación, o no hay puesto libre	Ninguno
404	Un id, tipo de recurso, esquema o ruta desconocidos	Ninguno
405	Un método que la ruta no acepta. La cabecera Allow lista los métodos aceptados.	Ninguno
409	Un userName, correo o nombre de grupo duplicado, o un nombre de grupo que ya tiene un grupo creado en Probara	uniqueness
413	Un cuerpo mayor de 1 MB	Ninguno
415	Un cuerpo enviado con un tipo de medio distinto de application/scim+json o application/json	Ninguno
429	El token alcanzó su límite de peticiones. La cabecera Retry-After indica la espera en segundos.	Ninguno
500	Un fallo inesperado. Vuelve a enviar la petición.	Ninguno
501	/Bulk, /Me o /.search	Ninguno

Las respuestas usan application/scim+json; charset=utf-8. Una petición con cuerpo debe usar application/scim+json o application/json, con o sin parámetros.

Límites

Límite	Valor
Cuerpo de la petición	1 MB. Un cuerpo mayor responde 413.
Peticiones por token	250 cada 10 segundos, es decir, 25 por segundo. Por encima de ese límite, la respuesta es 429 con Retry-After: 10.
Tamaño de página	Hasta 100 recursos por página
Caducidad del token	Obligatoria, como máximo 365 días
Tokens activos	Dos por organización

Lista de comprobación

• GET /ServiceProviderConfig responde 200 con tu token.
• POST /Users responde 201 con cabecera Location, y una segunda creación con el mismo userName responde 409.
• Un PATCH que pone active en false responde 200 y deja el registro visible en GET /Users.
• Una petición sin un token válido responde 401.

Siguiente paso

Lee la guía de aprovisionamiento SCIM para los pasos de configuración de Okta, Microsoft Entra ID y clientes SCIM 2.0 genéricos.