Autenticación (Authentication)

Resumen

Este módulo te permite implementar autenticación segura en tu aplicación mediante biometría o passkeys. Ideal para:

• Proteger operaciones críticas y datos sensibles
• Reducir fraudes y accesos no autorizados
• Centralizar el mecanismo de autenticación para toda tu plataforma

¿Cómo funciona?

Soyio utiliza Autenticación Fuerte (SCA, por sus siglas en inglés) o autenticación biométrica, para asegurar que sólo los usuarios autorizados realicen operaciones críticas. Esta solución de autenticación reduce significativamente el riesgo de fraude y acceso no autorizado, cumpliendo con estrictas normativas de seguridad.

El proceso de autenticación sigue estos pasos:

1. Se le ofrece al usuario la opción de usar su llave de acceso (passkey) guardada en su dispositivo
2. Si el usuario no tiene una passkey registrada, podrá optar por la autenticación facial

El flujo que integrarás es el siguiente:

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Pre requisitos

• El usuario debe tener una identidad creada en el sistema.
• Tener el SDK instalado en tu sitio o aplicación.
• Tener un Webhook configurado en tu cuenta.

Consideraciones de seguridad

• Manejo del auth_attempt_id: Nunca almacenes o transmitas este ID de forma insegura
• Timeout: Los intentos de autenticación expiran después de 5 minutos
• Rate limiting: Existe un límite de intentos por usuario/hora
• Validación: Siempre valida el resultado de la autenticación en tu backend

Paso a paso

1. Crea una solicitud de autenticación

Cuando quieras que un usuario se autentique, realiza un POST request desde tu back-end al endpoint de autenticación de Soyio. Esto creará una solicitud de autenticación y obtendrás un auth_attempt_id, que utilizarás en el siguiente paso.

Endpoint

POST /api/v1/authentication_requests

Ejemplo del payload

Especifica en el payload del request el identity_id de tu usuario. Puedes revisar más detalles en la documentación de la API.

{
  "identity_id": "id_...",
  "user_reference": "<identificador de usuario de la empresa>",
  "user_email": "<email del usuario>"
}

2. Inicia el proceso de autenticación

Inicia el proceso de autenticación desde el front-end de tu aplicación utilizando el SDK de Soyio.

Importante

Para evitar que el navegador bloquee el popup, asegúrate de que el widget se inicialice solo a través de una interacción directa del usuario, como un clic, debido a las políticas de seguridad del navegador contra ventanas emergentes. Revisa mas detalles en la documentación de nuestros SDKs.

Ejemplos

A continuación te dejamos ejemplos de cómo inicializar el flujo de autenticación en nuestros SDKs:

SDK Web

<button id="start-authentication-request">Start authentication request</button>

<script>
    import { SoyioWidget } from "@soyio/soyio-widget";

    // Configuración
    const widgetConfig = {
        request: "authentication",
        configProps: {
            authAttemptId: "<auth_attempt_id>",
        },
        onEvent: (data) => console.log(data)
    };

    // Creación del widget
    function initWidget() {
        new SoyioWidget(widgetConfig);
    }

    // Añade un escuchador de eventos al botón para inicializar el widget al hacer clic
    document
        .getElementById("start-authentication-request")
        .addEventListener("click", initWidget);
</script>

SDK Mobile

import { useSoyioAuth } from "@soyio/soyio-rn-sdk";

export default function App() {

    // Configuración
    const options = {
        uriScheme: "<company custom uri scheme>"
    };

    const authenticationParams = {
        authAttemptId: "<auth_attempt_id>"
    };

    const onEventChange = (event) => {
        console.log("Event:", event);
    };

    const { authenticate } = useSoyioAuth({ options, onEventChange });

    // Inicia el proceso de autenticación
    const initAuthenticationRequest = () => {
        authenticate(authenticationParams);
    };

    // Botón para iniciar el proceso
    return (
        <View>
        <Button title="Authentication request" onPress={initAuthenticationRequest} />
        </View>
    );
}

Detalles

Para más detalles sobre la configuración revisa las instrucciones del Readme del respectivo SDK:

• SDK Web.
• SDK Mobile.

3. Escucha los eventos en el front-end de tu aplicación

A medida que el usuario complete el flujo, se emitirán eventos que informan sobre el estado del proceso y dependiendo del caso, tu sistema deberá manejarlos. Cuando el usuario complete el proceso exitosamente se emitirá un evento de AUTH_SUCCESSFUL.

A continuación te detallamos los eventos que puedes escuchar:

SDK Web

Evento	Descripción
AUTH_SUCCESSFUL	El usuario se autenticó exitosamente.
AUTH_FAILED	El usuario no se autenticó exitosamente.
WIDGET_CLOSED	El usuario cierra el popup de Soyio.
WIDGET_OPENED	El usuario abre el popup de Soyio.
UNEXPECTED_ERROR	Ocurrió un error inesperado en el proceso de autenticación.

SDK Mobile

Evento	Descripción
success	El usuario se autenticó exitosamente.
failure	El usuario no se autenticó exitosamente.
open	El usuario abre el webview.
cancel	El usuario cierra el webview.
error	El usuario sale debido a un error.

Detalles

Para más detalles sobre los eventos revisa las instrucciones del Readme del respectivo SDK:

• SDK Web.
• SDK Mobile.

4. Escucha los eventos en el back-end de tu aplicación

Cuando el usuario se autentique exitosamente se emitirá un evento auth_attempt.successful. Esto lo recibirás mediante el webhook configurado en tu cuenta.

Ejemplo

Autenticación exitosa

{
    id: "evt_...",
    name: "auth_attempt.successful",
    payload: {
        user_reference: "<user-reference>",
        auth_attempt_id: "aa_...",
        identity_id: "id_..."
    },
    created_at: "<created_at>"
}

Autenticación fallida

{
    id: "evt_...",
    name: "auth_attempt.failed",
    payload: {
        user_reference: "<user-reference>",
        auth_attempt_id: "aa_...",
        error_reason: "passive_liveness_verification_not_passed",
        errors_array: [
        {
            code: "auth-XXX",
            type: "facial",
            message: "passive_liveness_verification_not_passed",
            detail: "La verificación de vivacidad pasiva no fue exitosa."
        },
        ...
        ]
    },
    created_at: "<created_at>"
}

5. Prueba tu integración

Para probar tu integración, en ambiente de pruebas (Sandbox) puedes utilizar el parámetro force_error en el payload de la solicitud de autenticación, tanto en el backend como en el frontend. Por ejemplo, puedes simular una autentiación fallida pasando force_error: "authentication_error".