Verificar la identidad en el widget

La clave del widget va en tu página, así que cualquiera puede copiarla, y el userId lo pone el navegador. Sin más, quien copie la clave puede leer y escribir los tickets de otra persona con solo cambiar ese valor. La verificación de identidad lo impide: tu servidor, que sabe quién ha iniciado sesión, firma el userId con el secreto del widget, y UTILIA OS comprueba la firma en cada petición antes de enseñar o tocar los tickets de esa persona.

Cómo funciona

El secreto del widget es distinto de la clave de API de la aplicación y de su clave de firma de los avisos. Cada aplicación tiene el suyo.

Antes de empezar

• La versión 1.2.0 del widget (@utilia-os/widget), que trae la opción userSignature y sus atributos. Todavía no está publicada: hasta entonces, el widget que instalas no manda la firma. Por eso las aplicaciones nuevas nacen en Solo avisar: no bloquea a nadie y te deja ver qué fallaría.
• El permiso «Editar las aplicaciones creadas por la empresa» para generar el secreto y cambiar el modo. Generar el secreto pide además la verificación en dos pasos.
• Un servidor que pinte la página del widget sabiendo quién ha iniciado sesión.

Paso a paso

1. Genera el secreto del widget

   Abre la aplicación en Ajustes, Creadas por tu empresa y entra en Configuración › Ajustes, pestaña Widget. En el bloque Verificación de identidad, pulsa Generar el secreto o, si ya hay uno, Renovar el secreto, y confirma con tu segundo paso.

   El secreto (empieza por utw_) se enseña una sola vez: cópialo y pulsa Ya lo he guardado.

2. Guárdalo en tu servidor

   En una variable de entorno o en tu gestor de secretos, como UTILIA_WIDGET_SECRET. Nunca en la página, en el repositorio ni en una aplicación móvil.

3. Firma el userId al pintar la página

   La firma es el HMAC-SHA256 del userId con el secreto, en hexadecimal. Calcúlala sobre el mismo valor exacto que le pasas al widget.

   Node.jsPHPPython

   import { createHmac } from 'node:crypto';
    
   const userSignature = createHmac('sha256', process.env.UTILIA_WIDGET_SECRET)
     .update(user.id)
     .digest('hex');

4. Pásale la firma al widget

   Junto al userId, con la forma de instalarlo que uses:

   • Etiqueta de script: data-user-signature="...".
   • Paquete npm: la opción userSignature.
   • Componente web: el atributo user-signature.

   El widget la manda en la cabecera X-Utilia-User-Signature de cada petición.

5. Elige el modo

   En el mismo bloque, Cómo se comprueba: empieza por Solo avisar y, cuando todas las páginas del widget manden la firma, cambia a Obligatoria.

Los tres modos

Se comprueba en las peticiones que llevan un userId hechas con una clave publicada: la de una aplicación con dominios autorizados, o una que se ha usado desde un navegador. Desde tu servidor, con la clave de una aplicación sin dominios autorizados, no se comprueba: esa clave es secreta y quien la usa ya es tu servidor. Las conexiones de eventos en tiempo real quedan atadas al userId con el que se pidió su pase.

Si ya usas el widget

Las aplicaciones creadas antes de que existiera la verificación están en Desactivada: siguen funcionando como siempre, y su diagnóstico avisa con widget-identity-not-verified. Para pasar a la verificación sin cortes:

1. Actualiza el widget a la 1.2.0.
2. Genera el secreto y firma el userId en tu servidor.
3. Pon el modo en Solo avisar mientras despliegas la firma en todas las páginas que cargan el widget.
4. Cambia a Obligatoria. Si alguna página quedó sin firmar, sus peticiones aparecen rechazadas en la pestaña Pruebas de la aplicación.

Las aplicaciones nuevas nacen en Solo avisar y sin secreto. Cuando vayas a firmar, genera el secreto en el panel del widget (se enseña una sola vez) y, con el widget 1.2.0 firmando, pasa a Obligatoria.

Renovar el secreto

Al renovarlo, el anterior deja de valer en el acto. Con el modo en Obligatoria, hasta que tu servidor firme con el nuevo, el widget no identifica a nadie. Para renovarlo sin cortes, pasa antes a Solo avisar, renueva, actualiza tu servidor y vuelve a Obligatoria.

Si algo falla

• 403 WIDGET_IDENTITY_REQUIRED: la petición no trae la firma. Comprueba que pasas userSignature al widget y que usas la versión 1.2.0. Ver el error.
• 403 WIDGET_IDENTITY_INVALID: la firma no corresponde a ese userId. Se calculó con un secreto que ya no vale, para otro usuario o sobre otro valor. Ver el error.
• 403 WIDGET_IDENTITY_SECRET_MISSING: el modo es Obligatoria y la aplicación no tiene secreto. Genéralo. Ver el error.
• «Con la verificación obligatoria y sin secreto, el widget no identifica a nadie.»: lo dice el bloque cuando falta el secreto. Pulsa Generar el secreto.