Autentica usuarios

Autentica usuarios

Esta guía te llevará paso a paso para implementar autenticación en tu aplicación usando Soyio.

Prerequisitos

Antes de comenzar, asegúrate de tener:

• Tu cuenta empresa en Soyio y tus credenciales de API.
• El SDK instalado en tu sitio o aplicación.
• Un Webhook configurado en tu cuenta para recibir los eventos de autenticación.

Si aún no tienes tu cuenta empresa en Soyio, contacta a nuestro equipo a hola@soyio.id para consultar por los planes disponibles y obtener una cuenta de prueba.

Consideraciones de seguridad

• Manejo del auth_request_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

Flujo de autenticación

El proceso de autenticación sigue estos pasos:

1. Si el usuario tiene una llave de acceso (passkey) registrada, se le mostrará la opción de usarla para autenticarse.
2. Alternativamente, el usuario podrá siempre optar por usar una autenticación facial.
3. El sistema valida la autenticación y genera evidencia del proceso

Diagrama de secuencia

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.

Paso a paso

1. Crea la identidad verificada del usuario

Utiliza el módulo de verificación de identidad para crear la identidad verificada del usuario en el sistema. Necesitarás que el usuario complete el flujo de verificación de identidad al menos una vez para crear su identidad verificada.

Cuando hayas creado la identidad verificada del usuario, podrás crear múltiples solicitudes de autenticación para ese usuario para todas tus operaciones críticas.

Te recomendamos leer el paso a paso del módulo de verificación de identidad para integrarlo en tu flujo de onboarding o registro en tu aplicación.

2. Crea la solicitud de autenticación

Crea un auth_request desde tu backend utilizando el endpoint de autenticación de Soyio.

Endpoint

POST /api/v1/auth_requests

Ejemplo del Payload

Especifica en el payload del request el identity_id del usuario previamente creado en el sistema.

{
  "identity_id": "id_..."
}

Ejemplo de Implementación

// Backend - Node.js/Express
const createAuthRequest = async (identityId) => {
  const response = await fetch('https://app.soyio.id/api/v1/auth_requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SOYIO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      identity_id: identityId
    })
  });

  const data = await response.json();
  return data.auth_request_id;
};

Revisa la referencia del API para Crear un request de autenticación para mas detalles.

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

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 más 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

<!-- HTML -->
<button id="start-auth-request">Start auth request</button>

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

    // Configuración
    const widgetConfig = {
        request: "authentication_request",
        configProps: {
            authRequestId: "<auth_request_id>",
            customColor: "<custom_color>"
        },
        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-auth-request")
        .addEventListener("click", initWidget);
</script>

SDK Mobile

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

export default function App() {

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

    const authRequestParams = {
        authRequestId: "<auth_request_id>"
    };

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

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

    // Inicia el proceso de autenticación
    const initAuthRequest = () => {
        authentication(authRequestParams);
    };

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

Modo embebido

Usa AuthRequestBox si necesitas mostrar la autenticación dentro de tu aplicación en lugar de abrir el widget en un popup.

<div id="embedded-auth-request"></div>

<script type="module">
  import { AuthRequestBox } from "@soyio/soyio-widget";

  const authRequestBox = new AuthRequestBox({
    authRequestId: "<auth_request_id>",
    customColor: "<custom_color>", // opcional
    isSandbox: true, // opcional
    onReady: () => {
      console.log("Embedded auth request ready");
    },
    onEvent: (event) => {
      if (event.eventName === "AUTH_REQUEST_SUCCESSFUL") {
        console.log("Autenticación exitosa", event.identityId);
      }
    },
  });

  authRequestBox.mount("#embedded-auth-request");
</script>

El modo embebido soporta autenticación facial con FaceTec dentro del iframe. Cuando el usuario elige una passkey, el SDK abre un popup temporal, completa la autenticación y retorna automáticamente al flujo embebido.

Configuración obligatoria de CSP

Registra en whitelisted_domains todos los dominios donde montarás AuthRequestBox. Si el origen no está permitido, el navegador bloqueará el iframe mediante la directiva CSP frame-ancestors. Revisa el formato de dominios permitidos.

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

• SDK Web.
• SDK Mobile.

4. Escuchar Eventos en el Frontend

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. Al completar la autenticación, AuthRequestBox emite AUTH_REQUEST_SUCCESSFUL; el widget popup mantiene CLOSE_POPUP por compatibilidad.

A continuación te detallamos los eventos que puedes escuchar. Encuentra todos los eventos que emite Soyio, con su payload, en el catálogo de eventos:

SDK Web

Evento	Descripción
AUTH_REQUEST_SUCCESSFUL	El usuario se autenticó exitosamente en AuthRequestBox.
CLOSE_POPUP	El usuario se autenticó exitosamente en el widget popup.
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.

Ejemplo de Manejo de Eventos

// Frontend - Web
const onEvent = (event) => {
  switch (event.type) {
    case 'AUTH_REQUEST_SUCCESSFUL':
    case 'CLOSE_POPUP':
      console.log('Autenticación exitosa');
      // Redirigir al usuario o actualizar la UI
      break;
    case 'WIDGET_CLOSED':
      console.log('Widget cerrado por el usuario');
      break;
    case 'UNEXPECTED_ERROR':
      console.error('Error inesperado:', event.error);
      break;
  }
};

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

• SDK Web.
• SDK Mobile.

5. Escuchar Eventos en el Backend

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

Eventos de Webhook

• auth_request.successful: El usuario se autenticó exitosamente
• auth_request.failed: El usuario no se autenticó, pero puede recuperarse

Estructura del Webhook

Autenticación exitosa

{
    id: "evt_...",
    name: "auth_request.successful",
    payload: {
        user_reference: "<user-reference>",
        auth_request_id: "authreq_...",
        identity_id: "id_..."
    },
    created_at: "<created_at>"
}

6. Obtener Resultado de Autenticación

Después de recibir el webhook, puedes obtener los detalles completos del resultado de autenticación.

// Backend - Node.js/Express
const getAuthResult = async (authRequestId) => {
  const response = await fetch(`https://app.soyio.id/api/v1/auth_requests/${authRequestId}`, {
    headers: {
      'Authorization': `Bearer ${process.env.SOYIO_API_KEY}`
    }
  });

  const data = await response.json();
  return data;
};