> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aprovisionamiento con SCIM 2.0

> Aprovisione usuarios y grupos desde su directorio con SCIM 2.0 en VU ONE FREE. Cree el token bearer en la consola y pruebe alta, listado y PATCH.

Esta página explica cómo aprovisionar usuarios y grupos de VU ONE FREE con SCIM 2.0. Su directorio de identidades envía los cambios de usuarios y grupos a VU ONE. Verá cómo crear el token, cómo llamar a cada operación y qué operaciones no están soportadas. Al terminar, usted puede crear, listar, actualizar y dar de baja usuarios con `curl`, igual que lo hará su directorio.

> [!WARNING]
>
> **VU ONE FREE es una versión limitada, en vista previa.** Solo la usan las cuentas de Identity Link que VU seleccionó hasta la disponibilidad general. Algunas funciones son del plan pago y las funciones, los límites y esta documentación pueden cambiar. [Vea qué incluye](https://docs.vu-one.com/vu-one/plan-free.md).

## Antes de empezar

* Un tenant de VU ONE FREE. SCIM está incluido en el plan gratuito.
* Un token SCIM. Lo crea en la consola, en la página [SCIM](https://docs.vu-one.com/vu-one/admin/scim.md).
* `curl` y `jq` en su equipo.

## Crear el token SCIM

Cree el token en la consola, en la página de SCIM de su tenant. El token aparece en el momento de la creación. Cópielo y guárdelo en su directorio. Si pierde el valor, cree un token nuevo.

> [!WARNING]
>
> El token SCIM da acceso a los usuarios y grupos del negocio asociado. Trátelo como una contraseña. No lo incluya en código ni en repositorios.

Cada token opera sobre un solo negocio y un solo proveedor de identidad del tenant. El token no puede tocar recursos de otro negocio.

## URL base

Las llamadas SCIM usan la misma base que la API, con el prefijo `/scim/v2`:

```text theme={null}
https://<tenant>.prod.vu-one.com/middleware/scim/v2
```

Defina estas variables antes de seguir los ejemplos:

```bash theme={null}
export TENANT_HOST="wispy-waterfall-3912.prod.vu-one.com"  # reemplace por el host de su tenant
export SCIM_TOKEN="<token-scim>"
```

El token SCIM es distinto del token OAuth (`$TOKEN`) que usan las demás páginas de la API.

## Autenticación

Envíe el token en el encabezado `Authorization`:

```bash theme={null}
curl -s "https://$TENANT_HOST/middleware/scim/v2/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .
```

Si la llamada no trae token, la API responde `401` con el encabezado `WWW-Authenticate: Bearer realm="scim"`. Si el token es inválido, vencido o revocado, la API responde `401` con `error="invalid_token"`. Si el token es válido pero no tiene permiso para la operación, la API responde `403` con `error="insufficient_scope"`.

## Crear un usuario

Envíe un `POST` a `/Users`. Los atributos de perfil, como `userName` y `displayName`, se toman de los claims configurados para el tenant.

```bash theme={null}
curl -s -X POST "https://$TENANT_HOST/middleware/scim/v2/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "externalId": "<id-en-su-directorio>",
    "userName": "<usuario>",
    "displayName": "<nombre-visible>",
    "active": true
  }' | jq .
```

La respuesta devuelve el usuario creado. Guarde el valor de `id`. Lo necesita para leer, actualizar o eliminar el usuario.

**schemas** `array` *required*

Debe incluir `urn:ietf:params:scim:schemas:core:2.0:User`.

**externalId** `string` *required*

Identificador del usuario en su directorio. Es único dentro del negocio y del tipo de recurso.

**userName** `string`

Nombre de usuario.

**displayName** `string`

Nombre visible del usuario.

**active** `boolean`

Estado del usuario.

## Listar usuarios

Use `startIndex` y `count` para paginar. Para buscar por nombre de usuario, use el parámetro `filter` con la sintaxis SCIM.

```bash theme={null}
curl -s "https://$TENANT_HOST/middleware/scim/v2/Users?startIndex=1&count=20" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .
```

```bash theme={null}
curl -s -G "https://$TENANT_HOST/middleware/scim/v2/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  --data-urlencode 'filter=userName eq "<usuario>"' | jq .
```

## Actualizar un usuario con PATCH

Envíe un `PATCH` a `/Users/{id}` con un mensaje `PatchOp`. Cada operación cambia un atributo.

```bash theme={null}
curl -s -X PATCH "https://$TENANT_HOST/middleware/scim/v2/Users/<user-id>" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      { "op": "replace", "path": "active", "value": false }
    ]
  }' | jq .
```

Si una operación del mensaje no es válida, la API no aplica ningún cambio del mensaje. Corrija el error y envíe el mensaje completo de nuevo.

## Eliminar un usuario

Envíe un `DELETE` a `/Users/{id}`. La API responde `204`.

```bash theme={null}
curl -i -X DELETE "https://$TENANT_HOST/middleware/scim/v2/Users/<user-id>" \
  -H "Authorization: Bearer $SCIM_TOKEN"
```

La baja es lógica. El usuario deja de aparecer en las consultas y en los listados. Las operaciones posteriores sobre ese identificador responden `404`. Si su directorio envía de nuevo el mismo `externalId`, VU ONE reactiva el registro y conserva su identificador.

## Grupos

Los grupos usan la misma forma que los usuarios, en la ruta `/Groups`. Puede crear, leer, actualizar y eliminar grupos con las mismas operaciones.

Al eliminar un grupo con SCIM, el grupo deja de estar administrado por SCIM. Sigue existiendo en VU ONE y un administrador puede modificarlo después.

## Recursos y operaciones

VU ONE expone dos recursos: `Users` y `Groups`. No existe el recurso `Roles`.

| Operación | Users | Groups | Notas |
| - | - | - | - |
| Alta (`POST`) | Sí | Sí | Exige `externalId`. |
| Consulta por identificador (`GET`) | Sí | Sí | |
| Listado filtrado (`GET`) | Sí | Sí | Paginación indexada con `startIndex` y `count`. |
| Búsqueda (`POST /.search`) | Sí | Sí | |
| Reemplazo (`PUT`) | Sí | Sí | Exige `externalId`. |
| Actualización parcial (`PATCH`) | Sí | Sí | Admite `valuePath`. |
| Baja (`DELETE`) | Sí | Sí | Es lógica. Responde `204`. |

No se soportan estas operaciones:

* `Bulk`. Una llamada a `/Bulk` responde `501`.
* `ETag` y el encabezado `If-Match`. Una solicitud con `If-Match` responde `501`.
* Cambio de contraseña por SCIM.
* Paginación por cursor.

> [!NOTE]
>
> El campo `externalId` identifica el usuario en su directorio. Es obligatorio en `POST` y en `PUT`. Puede cambiarlo, y el cambio conserva el mismo usuario en VU ONE.

## Errores

Los errores de SCIM usan los códigos HTTP estándar. Para la lista completa de formas de error y sus códigos, consulte [Errores de la API de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/errores.md).

| Respuesta | Causa |
| - | - |
| `401` con `WWW-Authenticate: Bearer realm="scim"` | Falta el token. |
| `401` con `error="invalid_token"` | El token es inválido, vencido o revocado. |
| `403` con `error="insufficient_scope"` | El token no tiene permiso para esta operación. |
| `404` | El recurso no existe, o ya fue eliminado. |
| `409` | Conflicto de unicidad, por ejemplo un `externalId` repetido. |

## Qué sigue

> [card] [Cuentas, identidades y contraseñas](https://docs.vu-one.com/vu-one/desarrolladores/cuentas.md)
>
> Consulte las cuentas y las identidades que crea SCIM.

> [card] [Errores de la API de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/errores.md)
>
> Entienda los errores de SCIM y de la API.

> [card] [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md)
>
> Use tokens OAuth para la API de negocio.

> [card] [SCIM en la consola](https://docs.vu-one.com/vu-one/admin/scim.md)
>
> Cree el token y configure los mapeadores de atributos.


## Related topics

- [Factores de autenticación en la API](https://docs.vu-one.com/vu-one/desarrolladores/factores.md)
- [VU ONE FREE frente al plan pago](https://docs.vu-one.com/vu-one/plan-free.md)
- [Configurar el aprovisionamiento SCIM](https://docs.vu-one.com/vu-one/admin/scim.md)
- [Guía para desarrolladores de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/introduccion.md)
- [Definir atributos y conjuntos de atributos](https://docs.vu-one.com/vu-one/admin/atributos.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.