Aprovisionamiento con SCIM 2.0

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.

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.

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.
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.

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:

https://<tenant>.prod.vu-one.com/middleware/scim/v2

Defina estas variables antes de seguir los ejemplos:

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:

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.

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.

array

requerido

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

string

requerido

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

string

Nombre de usuario.

string

Nombre visible del usuario.

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.

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

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.

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.

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.

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.

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

Cuentas, identidades y contraseñas

Consulte las cuentas y las identidades que crea SCIM.

Errores de la API de VU ONE FREE

Entienda los errores de SCIM y de la API.

Autenticación con OAuth 2.0 y OIDC

Use tokens OAuth para la API de negocio.

SCIM en la consola

Cree el token y configure los mapeadores de atributos.

Empezar aquí

Administración

Desarrolladores

Aprovisionamiento con SCIM 2.0

Antes de empezar

Crear el token SCIM

URL base

Autenticación

Crear un usuario

Listar usuarios

Actualizar un usuario con PATCH

Eliminar un usuario

Grupos

Recursos y operaciones

Errores

Qué sigue

Cuentas, identidades y contraseñas

Errores de la API de VU ONE FREE

Autenticación con OAuth 2.0 y OIDC

SCIM en la consola