Autenticación de terceros en Formulario Público

En algunas ocasiones, tu organización puede requerir que el Formulario Público solo pueda ser iniciado por ciertos usuarios, por ejemplo por tus clientes. En este caso, el inicio del proceso no debería estar habilitado de forma pública sino únicamente para aquellos usuarios que se hayan autenticado en tu sitio web.
Para estos casos Flokzu cuenta con la posibilidad de delegar el control de acceso al Formulario Público en tu propio sistema de autenticación.

Configuración

Una vez habilitado el Formulario Público en la configuración del proceso deberás habilitar la Autenticación del Formulario Público para ver las opciones de integración con tu sistema.





URL para el servicio de autenticación: Es la URL de un servicio REST de tu organización que se encargará de validar las credenciales del usuario.
URL para el servicio de notificación de borradores: Si además tienes habilitado la opción de Guardar en Borrador, deberás completar este campo con la URL del servicio REST al cual notificar cuando un borrador es guardado, o eliminado. De esta forma cuando el usuario se autentique en tu web podrá ver una lista de sus formularios en Flokzu guardados en borrador y podrá continuar con ellos.
Contenido que será agregado al mail del borrador: Es el contenido HTML que se agregará en el mail enviado al usuario final junto con el código de validación del borrador. Aquí deberás indicarle al usuario la URL o el mecanismo para acceder a sus borradores desde tu sistema.

¿Cómo funciona?

Si la autenticación de terceros se encuentra habilitada, el Formulario Público se comportará de la siguiente manera:

Acceder a un Formulario Público

Al acceder a un Formulario Público se consultará al servicio de autenticación configurado para permitir o denegar el acceso en función de la respuesta.
Si la autenticación es exitosa se devolverá la URL del formulario a la cual se deberá redirigir, y en caso contrario se le indicará Acceso denegado.

Guardar o actualizar un borrador

Al guardar en borrador el usuario recibirá un correo electrónico, en la dirección indicada en el encabezado, con el contenido del campo Contenido que será agregado al mail del borrador y el código de validación de su borrador. En el correo no indicaremos ninguna URL para acceder al borrador por fuera de tu sistema

Además se invocará el servicio configurado en URL para el servicio de notificación de borradores y se le enviará un webhook con status created o updated.
En la especificación de servicios podrás encontrar el formato del Webhook enviado.

Enviar un formulario

Cuando el usuario envía un formulario recuperado de sus borradores, la instancia de proceso es creada en Flokzu y el borrador es eliminado del sistema.
La eliminación es notificada a URL para el servicio de notificación de borradores con un webhook con status deleted

Descripción general de soluciones

1 - El usuario final accede a tu sitio web
2 - Selecciona la opción para crear una instancia.
3 - El sitio envía una solicitud a su backend para acceder al Formulario Público
4 - El backend genera las credenciales del usuario logueado y solicita al servicio de autenticación del formulario público de Flokzu que valide las credenciales
5 - El servicio de autenticación de formularios públicos:
a - Valida las credenciales con el servicio de autenticación de tu sitio
b - Devuelve la URL temporal que permite acceder al formulario público
6 - El backend devuelve la URL temporal al browser del usuario final
7 - El browser solicita el formulario público a Flokzu con la URL temporal


El siguiente diagrama de secuencia muestra la solución con el servicio de autenticación:




En este diagrama se asume que el sitio web del cliente necesita autenticación, que el usuario final ya está autenticado con el mismo de alguna manera y que el backend conoce el mail del usuario final.

Servicios externos

Son los servicios de autenticación de tu sitio web que deberás implementar según las siguientes especificaciones

Autenticación

Se espera que el servicio de autenticación externo funcione de la siguiente manera:

URL
POST - <url configurada en URL para el servicio de autenticación>

Header:
Email: <email>
Authorization: <token>

Los headers son los mismos que se deben enviar en la solicitud para abrir el Formulario Público.

Códigos de retorno:

401: Resultado si las credenciales no son válidas

JSON de respuesta

{
  "status": 401,
  "message": "Unauthorized"
}

200: Resultado si las credenciales son válidas y existe una sesión activa para este usuario

JSON de respuesta

{
  "status": 200,
  "message": "OK"
}

Recomendamos que el esquema de autenticación sigue la especificación de bearer authentication.

Notificación de borradores

URL:
POST - <url configurada en URL para el servicio de notificación de borradores>

Body:

{
  "Timestamp": <current-timestamp>,
  "Type": <draft-type>,
  "Payload": {
      "draft_id": <draft-id-encriptado>,
      "draft_url": "https://.../draft-url"
      "draft_status": <status>,
      "updated_at": <ultima-actualizacion>,
      "email": <email>,
      "authorization":  <token>
  }
}

Donde:

<current-timestamp>: es la fecha y hora en la que se realiza la solicitud al servicio. Se envía en formato extendido de ISO-8601 en UTC (ejemplo: 2021-03-03T16:18:05Z).
<draft-id-encriptado>: es el id encriptado del draft que ya se envía como parámetro de la URL.
<status>: puede tomar los valores “created”, “updated” o "deleted" en función de si se notifica cuando el draft fue creado por primera vez, actualizado y guardado nuevamente en borrador o eliminado.
<ultima-actualizacion>: fecha de última actualización del borrador. Esta fecha es usada para eliminar automáticamente los borradores con más de 60 días. Se envía en formato extendido de ISO-8601 en UTC.

Ten presente que debes eliminar de tu sistema todos los borradores con más de 60 días desde su última fecha de actualización.


Códigos de retorno:

200: Resultado si la actualización del estado del draft es exitosa.

JSON de respuesta

{ 
  "status": 200,
  "message": "OK"
}

- : Cualquier otra respuesta será considerada como inválida

Servicio de autenticación de formularios públicos

Es el servicios de Flokzu que deberás invocar desde tu backend

Este servicio protege el acceso a los formularios públicos y borradores que tienen configurada la autenticación de terceros.
El acceso al servicio está protegido con la misma APIKey que se utiliza para la OpenAPI.

URL
POST - https://app.flokzu.com/flokzuopenapi/api/<api-key>/publicform/authenticate

Headers
X-Username: <email>
X-Api-Key: <api-key>
Content-Type: application/json

Body

{
  "public-form-id": <public-form-id>,
  "draft-id": <draft-id>,
  "email": <email-usuario-final>,
  "authorization": <token>,
  "embedded": true/false
}

Donde:

<email>: es el mail de un usuario Flokzu, como se utiliza en la OpenAPI
<api-key>: es la APIKey del tenant, como se utiliza en la OpenAPI
<public-form-id>: es el identificador que puede encontrar en la URL del formulario público.
<draft-id>: es el identificador del draft, que fue enviado en la notificación mediante webhooks. Este valor es opcional y puede no estar presente en el caso que se solicita acceso para ingresar una nueva instancia.



Códigos de retorno:

401: Resultado si las credenciales no son válidas

JSON de respuesta

{
  "status": 401,
  "message": "Unauthorized"
}

422: Si el servicio de autenticación de tu sitio responde que las credenciales no son válidas

JSON de respuesta

{
  "status": 422,
  "message": "Invalid credentials"
}

200: Resultado si las credenciales son válidas y existe una sesión activa para este usuario

JSON de respuesta

{
  "status": 200,
  "public-form-url": ""
}

El servicio al recibir una solicitud:
1 - Verifica que las credenciales en los headers son válidas
2 - Luego obtiene el formulario público y valida si tiene configurada la autenticación de terceros
Si es así
a - Verifica que el email y el token sean válidos
b - Valida las credenciales del body (email y autorización) contra el servicio de autenticación
Si no es así devuelve un error como se explica en los códigos de retorno
3 - Si las credenciales son válidas entonces se genera un token temporal y devuelve la URL en el atributo public-form-url

La URL a devolver depende si se indicó un identificador de draft o no, según la siguiente lógica:

Sin draft-id

URL del formulario público con parámetros agregados:
auth con el token temporal generado
embedded solo si el parámetro embedded fue true al llamar este servicio

Ejemplo embebido
https://app.flokzu.com/public/01e1aLENCSEG?auth=eyJhb.eyJzIi._adss&embedded=true

Ejemplo no embebido
https://app.flokzu.com/public/01e1aLENCSEG?auth=eyJhb.eyJzIi._adss

Con draft-id

URL del formulario público con parámetros agregados:
p1 es el ID del draft encriptado
auth es el token temporal generado
embedded solo si el parámetro embedded fue true al llamar este servicio

Ejemplo embebido
https://app.flokzu.com/public/01e1aLENCSEG?p1=34lkj3oiu343h3l3&auth=eyJhb.eyJzIi._adss&embedded=true

Ejemplo no embebido
https://app.flokzu.com/public/01e1aLENCSEG?p1=34lkj3oiu343h3l3&auth=eyJhb.eyJzIi._adss

Generación del token

Dado que el token va a ser utilizado en un query param al acceder al formulario público, será un token de un solo uso para prevenir que alguien sin acceso lo utilice.
El token a generar será de 32 caracteres, y tiene implementado un control de colisiones.

Webhooks

En los casos donde se envía una notificación por webhooks el formato es el siguiente:

Body

{
  "Timestamp": <current-timestamp>,
  "Type": <draft-type>
  "Payload": {
    "draft_id": <draft-id-encriptado>,
    "public-form-id": <form-id-encriptado>,
    "draft_status": <status>,
    "updated_at": <ultima-actualizacion>,
    "email": <email>,
    "authorization": <authorization>
  }
}

Donde:
<form-id-encriptado>: es el ID del formulario público, el que genera la aplicación para acceder
<email> y <authorization>: son los que el servicio de autenticación guardó asociados al token temporal. Se envían al cliente para que pueda validarlos si lo desea.
<draftstatus>_: Puede tener los valores created , updated o deleted

Actualizado el: 27/08/2023