Control API - usuarios y aplicaciones de autenticación

Utilice FoxIDs Control API para aprovisionar usuarios internos y administrar las aplicaciones de autenticación registradas por cada usuario. Esta guía se centra en las operaciones que permiten sincronizar registros entre deployments de FoxIDs.

Antes de llamar a estas operaciones, configure la autenticación y los derechos de acceso de Control API. Swagger sigue siendo la referencia exacta para todas las propiedades de usuario, filtros, reglas de validación y esquemas de response:

• Swagger (OpenAPI) JSON
• Swagger UI

Base de endpoints

Los ejemplos utilizan FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Sustituya {tenant_name} por el nombre del tenant y {track_name} por el nombre técnico del entorno. Cambie el host para un deployment self-hosted. Envíe el access token de Control API en el header Authorization: Bearer {access_token}.

Las operaciones de usuarios y aplicaciones de autenticación requieren un derecho de usuario para el entorno de destino. Conceda solo la operación read, create, update o delete necesaria mediante la jerarquía de derechos de Control API.

Identificadores de usuario

Cada usuario interno debe tener al menos un identificador de inicio de sesión: correo electrónico, teléfono o nombre de usuario. Las direcciones de correo electrónico pueden tener hasta 100 caracteres y los nombres de usuario hasta 60 caracteres. Las direcciones de correo electrónico y los nombres de usuario se normalizan a minúsculas y se eliminan los espacios en blanco circundantes de todos los identificadores.

Las operaciones individuales identifican al usuario con el query parameter email, phone o username. La response también contiene un userId generado por el servidor. Es único y persistente, incluso si cambia un identificador, y debe usarse para asociar aplicaciones de autenticación u otros recursos.

Para usuarios de Directory Connector, conserve el vínculo estable directoryUserId al actualizar la cuenta. La sincronización bajo demanda sustituye identificadores, ajustes y claims gestionados por el directorio; cambie esos valores en el directorio autoritativo. Se conservan las aplicaciones de autenticación y asignaciones de acceso FoxIDs.

Operaciones de usuario

Las operaciones individuales se agrupan bajo tenant users en Swagger.

Los claims personalizados pueden incluir un valueType opcional: String, Boolean, Number, JsonObject o JsonArray. Todas las entradas de values siguen siendo cadenas y comparten el tipo seleccionado. Omita valueType para String. La API rechaza los valores que no coinciden con el tipo seleccionado; conserve el tipo al leer y actualizar claims. Las mismas opciones se aplican a los claims de nodos de estructuras de acceso y a los claims del administrador inicial al crear un tenant. Consulte tipos de valores de claims para conocer los límites numéricos y el comportamiento JWT/SAML.

Use phone={phone} o username={username} en lugar de email={email} cuando corresponda. Añada cada endpoint a la base de endpoints.

Listar y filtrar usuarios

GET /!users admite filterEmail, filterPhone, filterUsername, filterUserId y filterClaimValue. Cada filtro busca coincidencias parciales sin distinguir mayúsculas. Con varios filtros, se devuelve el usuario si cualquiera coincide.

La response contiene una collection data y un paginationToken opaco. Repita el mismo request con el valor devuelto como paginationToken para obtener la página siguiente. Continúe hasta que no haya token. No lo interprete ni modifique.

La response indica si hay contraseña y cuándo cambió por última vez, pero nunca devuelve la contraseña ni su hash actual.

Crear un usuario

El create-request admite estado de cuenta, identificadores verificados, claims personalizados, política de contraseña, configuración por correo o SMS y ajustes MFA por usuario. Este ejemplo crea un usuario sin contraseña y exige configurarla por correo:

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [
    {
      "claim": "role",
      "values": ["employee"]
    }
  ]
}

Un create-request puede incluir contraseña en texto claro, campos de hash admitidos o ninguna credencial. Nunca envíe ambos formatos. Las contraseñas en claro se validan con la política elegida; los hashes importados no. Sin credenciales, use setPasswordEmail o setPasswordSms si el usuario debe crear una contraseña al iniciar sesión.

Crear un usuario existente devuelve 409 Conflict y se aplica el límite de usuarios del plan del tenant. Una operación de usuario simultánea puede bloquear temporalmente la creación; reintente 423 Locked tras una breve espera.

Actualizar un usuario

PUT /!user es una actualización completa, no un patch. Lea el usuario actual, conserve las propiedades sin cambios, aplique los cambios y envíe toda la representación editable. La collection de claims y los flags de cuenta/MFA se sustituyen. Las contraseñas y registros de aplicaciones tienen operaciones propias.

Identifique al usuario con email, phone o username. Para cambiar un identificador, mantenga su valor actual y establezca updateEmail, updatePhone o updateUsername. Una cadena vacía lo elimina; omitir la propiedad lo conserva. Mantenga al menos un identificador de inicio de sesión.

Cambiar disableAccount de false a true revoca los refresh token grants y sesiones activas. Reactivar permite nuevos inicios de sesión, pero no restaura las sesiones revocadas.

Las reclamaciones personalizadas de los usuarios no pueden utilizar nombres de reclamaciones protegidos, como sid y auth_time.

Administrar contraseñas

Use PUT /!usersetpassword para establecer una contraseña administrativamente o migrarla. Admite tres modos:

• Proporcione password para aplicar la política seleccionada y actualizar el historial.
• Proporciona passwordHashAlgorithm y passwordHash, además de passwordHashSalt cuando el algoritmo lo requiera, para importar un hash precalculado compatible sin validar la política.
• Omita ambos formatos para eliminar la contraseña actual del usuario.

Se aceptan los mismos formatos de hash al crear un usuario o aprovisionar en masa:

Por ejemplo, esta petición administrativa de contraseña importa un hash bcrypt sintético:

{
  "email": "alice@example.com",
  "passwordHashAlgorithm": "bcrypt",
  "passwordHash": "$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC"
}

No incluyas password junto con los campos de hash. Un hash o una sal sin su algoritmo se rechaza. Las cadenas bcrypt mal formadas, las variantes no compatibles, los costes fuera del intervalo y las sales bcrypt separadas se rechazan antes de guardar. Consulta el hashing de contraseñas para los parámetros y el límite de 72 bytes de bcrypt.

El valor opcional passwordLastChanged es tiempo Unix en segundos. Utiliza changePassword para exigir que el usuario elija una contraseña nueva en el siguiente inicio de sesión aplicable. Importar un hash omite las comprobaciones de política durante la importación; la política seleccionada sigue aplicándose al iniciar sesión. El inicio de sesión conserva el hash importado y la fecha de cambio. Establecer o cambiar una contraseña en texto plano utiliza el formato PBKDF2 predeterminado.

Use PUT /!userchangepassword cuando conozca la contraseña actual. Verifica esta y valida la nueva con la política e historial del usuario.

El endpoint del historial de contraseñas está destinado a escenarios controlados de migración y recuperación. También acepta entradas bcrypt con los mismos límites de formato y coste y sin sal separada. Su respuesta detallada contiene material de hashes y PUT sustituye todo el historial. Aplica las mismas medidas de protección que a los hashes importados y no registres los cuerpos de peticiones o respuestas.

Aprovisionamiento masivo

PUT /!users admite entre 1 y 1.000 usuarios por request. Como máximo 100 entries pueden incluir contraseñas en claro. Los requests sin ellas, incluidos hashes precalculados admitidos, pueden incluir 1.000 usuarios.

La carga masiva crea nuevos usuarios o sustituye a los que coinciden; no combina propiedades individuales ni puede cambiar los identificadores de correo electrónico, teléfono o nombre de usuario. Trátela como una importación de sustitución. Use la actualización individual para los cambios habituales del ciclo de vida de la cuenta cuando deban conservarse el estado existente y el ID de usuario persistente.

DELETE /!users admite entre 1 y 1.000 correos, teléfonos o nombres de usuario en userIdentifiers. Consulte Cargar muchos usuarios para formatos, rendimiento y seed tool.

Eliminar usuarios y revocar acceso

La eliminación individual o masiva revoca refresh token grants y sesiones activas antes de borrar la cuenta. Es permanente. Use las operaciones delete de aplicaciones de autenticación para quitar solo sus registros.

Los requests de creación, actualización, contraseña y eliminación se incluyen en el audit log de Control. Las lecturas no se escriben como audit-events.

Bloqueos por errores de inicio de sesión

Use las operaciones de lista y detalle para revisar bloqueos y elimine uno cuando un administrador autorice finalizarlo.

Los bloqueos por usuario tienen un userIdentifier. Use ese valor y el tipo de fallo para obtener o finalizar un bloqueo. El filtro de lista filterUserIdentifier compara identificadores sin distinguir mayúsculas de minúsculas.

Los bloqueos DirectorySynchronisation tienen un sequenceId y omiten userIdentifier. Use el sequenceId exacto, sensible a mayúsculas, y el tipo de fallo para obtener o finalizar el bloqueo de sincronización, sin el parámetro userIdentifier. Use filterSequenceId para encontrar bloqueos de esa secuencia. Si aporta filterUserIdentifier y filterSequenceId, se encuentran bloqueos coincidentes con cualquiera; el filtro de tipo de fallo sigue aplicándose a todos. El límite de búsquedas lo comparten todos los identificadores introducidos en la misma secuencia.

Registros de aplicaciones de autenticación

Las operaciones de aplicaciones de autenticación se agrupan bajo tenant user authenticator apps en Swagger. Una operación de lista devuelve resúmenes seguros, mientras que la operación de detalle devuelve los datos confidenciales necesarios para una sincronización controlada.

Añada cada endpoint a la base de endpoints. Por ejemplo:

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Recurso de registro

La creación y la actualización utilizan el recurso de registro completo:

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

Las propiedades se comportan del siguiente modo:

• userId es el ID estable del usuario de FoxIDs.
• id es un ID de registro persistente proporcionado por el cliente al crear. Selecciona el registro al actualizar y no puede cambiarse.
• createTime se expresa en segundos Unix. Es opcional al crear y de forma predeterminada usa la hora actual. Si se omite al actualizar, se conserva el valor existente.
• secret es el TOTP secret compartido y es obligatorio al crear y actualizar.
• recoveryCode contiene los datos de hash del recovery code y se omite cuando no hay un recovery code configurado.

Un usuario puede tener como máximo cinco registros de aplicaciones de autenticación. Crear con un ID existente devuelve 409 Conflict; crear después de alcanzar el límite devuelve 400 Bad Request.

Sincronizar registros

Un servicio de sincronización puede combinar la Authenticator App notification API interactiva con estas operaciones de Control API:

1. Reciba la notification registered que contiene user_id y registration_id.
2. Obtenga el registro del source deployment mediante la operación de detalle.
3. Cree el registro en el target deployment o actualícelo si ya existe el mismo ID.

Las operaciones de Control API para crear, actualizar y eliminar no llaman a la Authenticator App notification API. Por tanto, la sincronización no genera un bucle de notification.

Seguridad

Las operaciones de detalle, creación y actualización exponen o aceptan un secret de aplicación de autenticación y datos de hash del recovery code. Conceda el derecho de usuario necesario solo a clientes de confianza, utilice TLS, proteja los payloads almacenados y no registre los request o response bodies.

Utilice la operación de lista cuando solo necesite los ID de registro y las horas de creación. No devuelve el secret ni los datos de hash del recovery code.

Propiedad de compatibilidad

La propiedad activeTwoFactorApp de la API general de usuario está deprecated y se prevé eliminarla después del 1 de agosto de 2027. En una update-request, false sigue eliminando todos los registros por compatibilidad; true o un valor omitido los deja sin cambios. Las integraciones nuevas deben usar los endpoints de aplicaciones de autenticación.

Responses de error

Los responses de error habituales de usuarios y aplicaciones de autenticación son:

• 400 Bad Request si los identificadores, credenciales, filtros o datos son inválidos, o se alcanzó el límite de registros.
• 401 Unauthorized si falta el access token o no es válido.
• 403 Forbidden si el cliente no tiene el derecho de usuario necesario para el entorno.
• 404 Not Found si el usuario o registro de aplicación no existe.
• 409 Conflict si el usuario ya existe o se reutiliza un ID de registro.
• 423 Locked si la creación o importación masiva está bloqueada temporalmente. Reintente tras una breve espera.

Utilice el response body para ver los detalles de validación. Consulte Swagger UI para los responses declarados por cada operación.

Sesiones suplantadas

Las sesiones activas conservan los identificadores del usuario autenticado original. Los detalles de suplantación identifican por separado al usuario de destino, incluidos su subject, formato de subject, correo electrónico, teléfono, nombre de usuario y referencia de cuenta interna cuando estén disponibles. Puede encontrar una sesión activa con los identificadores de cualquiera de los usuarios.

Los claims del token de actualización representan la identidad emitida a la aplicación; los detalles de suplantación del grant identifican al usuario autenticado original y al destino seleccionado. Ambas cuentas asociadas participan en la revocación de acceso. Consulte suplantación para configurar el flujo y conocer el comportamiento de las sesiones.

Documentación relacionada

• Autenticación y derechos de acceso de Control API
• Descripción general de FoxIDs Control
• Usuarios internos
• Autenticación de dos factores y multi-factor
• Cargar muchos usuarios