Comenzar con FaceAuth - ARGOS Identity

Lectura relacionada

Crear un proyecto FaceAuth en el panel y configurar la política (umbrales, liveness, oclusión) y la expiración del token → Guía de FACE AUTH
Aspectos comunes a todos los complementos (emisión de la clave API, cuotas de solicitudes, códigos de estado de respuesta HTTP) → Comenzar con complementos

Modos de entrega de FaceAuth — 2 opciones

FaceAuth puede entregarse de dos formas. Recomendamos el método Face Auth URL, que elimina la necesidad de implementar una UI de cámara propia y admite Active Liveness.

A. Face Auth URL (Recomendado)

La captura del selfie se realiza en una página alojada por ARGOS (similar a Liveform). No es necesario implementar una UI de cámara en el cliente, y la política del proyecto puede habilitar Liveness (Pasivo/Activo) y controles de oclusión (mascarilla/casco).

B. POST /faceauth API

Su aplicación implementa la UI de cámara y envía el archivo faceImage capturado al API. Active Liveness no es compatible — solo se compara la similitud facial.

Si le preocupan los intentos de suplantación (replays de pantalla, fotos impresas), utilice el método URL. El método POST API juzga una sola imagen enviada únicamente por similitud y no puede verificar que el usuario esté físicamente presente. El método URL le permite configurar un umbral de Liveness en la política del proyecto para bloquear ataques de replay de pantalla y fotos estáticas.

Para la configuración de políticas en el dashboard (umbrales, liveness, oclusión) y casos de uso de ambos métodos, consulte la Guía de FACE AUTH. El resto de esta página cubre los parámetros y el flujo de autenticación del Método A (Face Auth URL). Para el Método B (POST API), consulte la página POST/Faceauth.

QueryString para acceder a FaceAuth

FaceAuth es un subproyecto de ID Check, y los administradores pueden crear tantos proyectos como deseen. Para entregar autenticación adicional mediante el método Face Auth URL, utilice la URL de Face Auth dentro del proyecto Add-on.
Para hacer referencia a un submission_Id que ha sido aprobado a través de ID document o Knowledge-based donde existe una imagen selfie, se debe agregar a la URL mediante el parámetro de consulta encrypted, y por motivos de seguridad, siempre debe usarse en estado cifrado.
El cifrado debe utilizar la clave API dentro del proyecto FaceAuth y utiliza AES-256.
Para métodos detallados, consulte Cifrado de Cadena de Consulta.

El texto plano que se cifra es JSON — no una cadena de consulta.Si cifra una cadena formada por pares key=value unidos con & (por ejemplo sid=...&authUserId=...), el sid no se reconoce y la verificación no se inicia. Serialice un objeto JSON (JSON.stringify) y cifre esa cadena, y use el resultado como valor de encrypted.En ese caso la pantalla muestra “Página no encontrada” en lugar de una página con código de error, lo que dificulta identificar la causa. Para el orden de diagnóstico, consulte Validación de la URL de Face Auth y manejo de errores.

Face Auth no se ejecuta sin cadena de consulta.Una URL que solo lleve pid no inicia la verificación — el sid de referencia debe cifrarse y enviarse dentro de encrypted. Si falta, el usuario es redirigido a la página de error PV-40015.

Paso 1 — Prepare el texto plano (JSON) que va a cifrar

{
  "sid": "{submission_Id}"
}

{
  "sid": "{submission_Id}",
  "authUserId": "{user Id}",
  "authCf1": "{additional_info}",
  "authCf2": "{additional_info}",
  "authCf3": "{additional_info}",
  "token": "{any tokenId}"
}

Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

Estructura de la URL de Face Auth (esta forma por sí sola no se ejecuta)

  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}

El valor cifrado enviado en encrypted (forma ejecutable)

  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}

El valor de encrypted debe estar codificado para URL.El resultado del cifrado AES-256 (Base64) contiene +, / y =. Si lo añade a la URL sin codificar, + se interpreta como un espacio, por lo que el descifrado falla y no se puede leer el sid. Aplique encodeURIComponent (o la función de codificación de URL de su lenguaje).

Ejemplo completo en Node.js

const crypto = require('crypto');

function encrypt(data, apiKey) {
  const hashedKey = crypto.createHash('sha256').update(apiKey).digest();
  const cipher = crypto.createCipheriv('aes-256-ecb', hashedKey, null);
  return cipher.update(data, 'utf8', 'base64') + cipher.final('base64');
}

// Paso 1: el texto plano es un objeto JSON serializado
const queryData = JSON.stringify({
  sid: 'submission_12345',
  authUserId: 'user123',
});

// Paso 2: cifre con la clave API del proyecto FaceAuth y codifique para URL
const encrypted = encrypt(queryData, FACEAUTH_API_KEY);
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;

pid y lang no están sujetos a cifrado — añádalos como texto plano fuera de encrypted.

Definición de parámetros de solicitud

string

requerido

Número único asignado al proyecto al crear un proyecto FaceAuth (se adjunta automáticamente a la URL)

string

requerido

submission_Id aprobado a través de ID document o Knowledge-based (se usa sid para distinguir)

string

ID de usuario que el administrador asignará al usuario (puede ser el ID de usuario en el servicio del administrador o el mismo userId utilizado en ID document o Knowledge-based)

string

Información adicional que el administrador asignará al usuario (por ejemplo, dirección de correo electrónico, etc.)

string

Información adicional que el administrador asignará al usuario (igual que authCf1)

string

Información adicional que el administrador asignará al usuario (igual que authCf1)

string

Token que el administrador agregará a la URL con fines de seguridad.
¡Nota!: Este token opera de forma independiente del token preregistrado en modo privado.

Cómo funciona el token de FaceAuth

El token está diseñado para asignar una URL única a cada usuario cuando se autentican a través de FaceAuth.
Para aplicar un token, debe habilitar la opción de configuración de condición de expiración de token en el proyecto FaceAuth, y funciona de la siguiente manera:

Expiración basada en conteo: Cuando el token se usa una vez, el Token ID expira inmediatamente.
Expiración basada en tiempo: Cuando ha transcurrido el tiempo desde el momento en que el token se usó una vez, el Token ID expira.

Este token opera de forma independiente del token de modo privado del proyecto principal o del token preregistrado.
Por ejemplo, puede especificar un tokenId arbitrario establecido por el administrador en el token, e incluso si reutiliza el token usado en el proyecto principal, funciona porque se gestiona por separado. Para una guía sobre cómo habilitar la opción de configuración de condición de expiración de token en el proyecto FaceAuth, consulte Guía de FACE AUTH — Configuración de condiciones de expiración de Token.

string

Idioma de visualización de la pantalla de Face Auth. Use un código ISO 639-1 en minúsculas (por ejemplo, en, ko). No está sujeto a cifrado — añádalo en texto plano fuera de encrypted (por ejemplo, ?pid={faceAuth_projectId}&encrypted={encrypted}&lang=en). Si se omite, en móvil se usa el idioma del dispositivo y en PC el del navegador. Para la lista de idiomas admitidos, consulte Idiomas Soportados.

Para casos aprobados donde no existe imagen selfie, se utilizará en su lugar la imagen de retrato del documento de identidad.

Validación y manejo de errores de Face Auth URL

Referencia por etapas de los códigos de error generados por fallos de validación de QueryString, fallos de precarga y fallos de autenticación, junto con los mensajes que los usuarios ven realmente.

Endpoints de la API de FaceAuth

POST/FaceAuth

Envío de FaceAuth

GET/FaceAuth

Consulta de FaceAuth

GET/FaceAuth/Image

Consulta de imagen de FaceAuth

DELETE/FaceAuth

Eliminación de FaceAuth

Webhooks

Faceauth

Webhook de FaceAuth

Expiración de Token ID

Webhook de expiración de Token ID

​Modos de entrega de FaceAuth — 2 opciones

A. Face Auth URL (Recomendado)

B. POST /faceauth API

​QueryString para acceder a FaceAuth

​Paso 1 — Prepare el texto plano (JSON) que va a cifrar

​Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

​Definición de parámetros de solicitud

Validación y manejo de errores de Face Auth URL

​Endpoints de la API de FaceAuth

POST/FaceAuth

GET/FaceAuth

GET/FaceAuth/Image

DELETE/FaceAuth

​Webhooks

Faceauth

Expiración de Token ID

Modos de entrega de FaceAuth — 2 opciones

QueryString para acceder a FaceAuth

Paso 1 — Prepare el texto plano (JSON) que va a cifrar

Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

Definición de parámetros de solicitud

Endpoints de la API de FaceAuth

Webhooks