Aprovisionar grupos con SCIM

A través del endpoint /Groups, un sistema de aprovisionamiento gestiona los grupos de tu organización y sus miembros. Los grupos creados a través de SCIM son grupos normales: aparecen en Grupos en la consola de administración, y es allí donde les das acceso a aplicaciones, como a cualquier otro grupo.

Todas las rutas de abajo son relativas a la URL base de SCIM de tu organización. Los detalles del protocolo comunes a usuarios y grupos están en la referencia de la API SCIM.

Cómo se corresponden los atributos SCIM con BreezeAuth

Atributo SCIM	En BreezeAuth
id	El identificador del grupo en BreezeAuth.
displayName	Nombre. Obligatorio.
externalId	El identificador del grupo en el sistema de aprovisionamiento. BreezeAuth lo guarda, pero no aparece en la consola. Único en la organización.
members	Los miembros directos del grupo: usuarios y otros grupos.

BreezeAuth genera el Identificador del grupo a partir del nombre cuando se crea el grupo, por ejemplo equipo-de-ventas para “Equipo de Ventas”, con un número añadido si ya está en uso (equipo-de-ventas-2). Renombrar el grupo después no lo cambia. La Descripción del grupo no se gestiona a través de SCIM: puedes rellenarla en la consola de administración.

Miembros

Cada miembro se identifica por su id SCIM y su type:

"members": [
  { "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" },
  { "value": "9a8b7c6d-5e4f-4321-9876-0fedcba98765", "type": "Group" }
]

Campo	Descripción
value	El id de un usuario o de otro grupo.
type	User o Group. Obligatorio: un miembro sin un type válido se rechaza con 400 Bad Request.
display	Opcional, y BreezeAuth lo ignora.

Un miembro de tipo Group forma un grupo anidado: los usuarios del grupo interior pasan a ser miembros indirectos del exterior y reciben las aplicaciones asignadas a él. Un grupo no puede ser miembro de sí mismo.

SCIM solo muestra y cambia los miembros directos, los que se añadieron al propio grupo. Los miembros indirectos, que vienen de grupos anidados, no aparecen, lo que también corresponde a la opción Mostrar solo las asociaciones directas de la consola de administración.

Crear un grupo

POST /Groups
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Equipo de Ventas",
  "externalId": "grp-0042",
  "members": [{ "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" }]
}

BreezeAuth responde 201 Created con el nuevo grupo, y su dirección en la cabecera Location:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "9a8b7c6d-5e4f-4321-9876-0fedcba98765",
  "displayName": "Equipo de Ventas",
  "externalId": "grp-0042",
  "members": [{ "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" }],
  "meta": {
    "resourceType": "Group",
    "created": "2026-10-13T14:35:12.000Z",
    "lastModified": "2026-10-13T14:35:12.000Z",
    "location": "https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2/Groups/9a8b7c6d-5e4f-4321-9876-0fedcba98765"
  }
}

members es opcional: muchos sistemas de aprovisionamiento crean primero el grupo y añaden los miembros después.

Buscar y leer grupos

Petición	Devuelve
GET /Groups/{id}	Un grupo, con sus miembros directos.
GET /Groups	Todos los grupos de la organización, página a página, sin miembros.
GET /Groups?filter=displayName eq "Equipo de Ventas"	El grupo con ese nombre, si existe.
GET /Groups?filter=externalId eq "grp-0042"	El grupo con ese identificador externo, si existe.

Para obtener los miembros de un grupo, lee el propio grupo. Un grupo con más de 1000 miembros directos no se puede leer ni actualizar a través de SCIM: la petición falla con 400 Bad Request y scimType tooMany.

Actualizar un grupo

Reemplazar un grupo (PUT)

PUT /Groups/{id} reemplaza el nombre, el identificador externo y los miembros del grupo por el cuerpo que envías. La lista de miembros que envías pasa a ser la lista completa de miembros directos del grupo: los miembros que no están en ella se quitan, y no enviar members quita a todos los miembros. Si externalId queda fuera, se borra.

Cambiar algunos atributos (PATCH)

PATCH /Groups/{id} es la forma habitual de renombrar un grupo y de añadir o quitar miembros sin enviar la lista entera:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "b4c0d2e3-8f5a-4b7c-9d6e-0f1a2b3c4d5e", "type": "User" }]
    },
    { "op": "remove", "path": "members[value eq \"a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d\"]" }
  ]
}

Las operaciones compatibles son:

Operación	Ruta	Efecto
add	members	Añade los miembros de value. Los miembros que ya están en el grupo se ignoran.
replace	members	Reemplaza todos los miembros directos por los de value.
remove	members[value eq "{id}"]	Quita ese miembro.
remove	members	Quita a todos los miembros directos, sea cual sea el contenido de value.
add o replace	displayName	Renombra el grupo.
add o replace	externalId	Cambia el identificador externo.
remove	externalId	Borra el identificador externo.

Una operación add o replace también puede omitir path y enviar un objeto en value, con displayName, externalId y members. De esa forma, add añade los miembros y replace los reemplaza.

Las operaciones se aplican en el orden en que aparecen. Si una falla, por ejemplo porque un miembro no existe, las operaciones anteriores siguen aplicadas: lee el grupo para ver su estado actual antes de reintentar.

Eliminar un grupo

DELETE /Groups/{id}

Igual que en la consola de administración, un grupo solo se puede eliminar cuando no tiene miembros. Si no, la petición falla con 409 Conflict. Quita primero los miembros, por ejemplo con una operación remove en members, y después elimina el grupo.

Cuando se elimina el grupo, BreezeAuth responde 204 No Content. Las asignaciones de aplicaciones del grupo se eliminan con él. Esto no se puede deshacer.

Dar acceso a aplicaciones a los grupos aprovisionados

SCIM no asigna aplicaciones. Cuando exista un grupo aprovisionado, asigna sus aplicaciones en la consola de administración, una sola vez. A partir de entonces, todas las personas que el sistema de aprovisionamiento añada al grupo obtienen acceso automáticamente, y lo pierden cuando se las quita. Consulta Acceso a aplicaciones.