Configuración de JWT para el widget de la base de conocimientos

Si tu base de conocimientos es privada o está restringida a usuarios específicos, puedes usar JWT (JSON Web Tokens) para controlar de forma segura el acceso al widget Document360 incrustado. Esta configuración garantiza que solo los usuarios autenticados puedan ver los artículos a través del widget, sin necesidad de iniciar sesión por separado.

Con la autenticación JWT, tu sistema gestiona el inicio de sesión y la generación de tokens. El widget utiliza ese token para obtener contenido según el nivel de acceso de cada usuario.

En este artículo, aprenderás:

• Cómo funciona la autenticación JWT para widgets

• Cómo configurar los ajustes de JWT en el portal Document360

• Cómo configurar tu backend para generar y devolver tokens seguros

• Cómo probar tu configuración de JWT usando Postman

Cómo funciona la autenticación JWT para widgets

JWT es el enfoque recomendado cuando tu visibilidad de la base de conocimientos está configurada en Privado o Mixto. En estos casos, los lectores deben estar autenticados antes de que el widget pueda mostrar contenido. JWT gestiona esto de forma silenciosa: los lectores nunca ven una pantalla de inicio de sesión separada.

Usa JWT cuando:

• Tu base de conocimientos está restringida a usuarios o grupos de lectores específicos

• Quieres acceso único al widget sin necesidad de un aviso separado para iniciar sesión

• Necesitas controlar qué contenido ve cada lector según su pertenencia al grupo

Visión visual del proceso de autenticación

Este diagrama de flujo muestra lo que ocurre cuando un usuario carga un widget en tu sitio web. El widget Document360 se comunica con tu sistema para obtener un token seguro antes de mostrar el contenido.

Diagrama secuencial del proceso de autenticación

Este diagrama de secuencia describe el flujo técnico entre el navegador del usuario, tu backend y el servidor de identidad de Document360 para generar y validar el token JWT.

Los pasos siguientes explican el flujo completo de autenticación JWT:

1. El usuario visita tu sitio web, donde está incrustado el widget de Document360.

2. El widget envía una solicitud silenciosa a tu endpoint de autenticación (endpoint de token) configurado en la configuración del widget.

3. Tu backend envía una solicitud a Document360 con las credenciales requeridas (ID del cliente, secreto del cliente) y los detalles del lector.

4. Document360 valida la solicitud y devuelve un JWT firmado a tu backend.

5. Tu backend envía el token de vuelta al widget.

6. El widget utiliza este token para obtener y mostrar artículos a los que el lector tiene acceso.

7. Cuando el token expira, el widget solicita automáticamente uno nuevo (si está configurado para hacerlo).

NOTA
El flujo anterior ocurre entre bastidores. Los lectores nunca ven una pantalla de inicio de sesión para el widget.

Antes de que empieces

Antes de configurar JWT para el widget, asegúrate de lo siguiente:

• Tienes un rol de Propietario de Proyecto o Administrador en Document360.

• Ya tienes al menos un widget de base de conocimiento creado. Si no, crea uno primero desde el widget de Conexiones > Knowledge Base.

• La visibilidad de tu base de conocimientos está configurada como Privada o Mixta. JWT no es obligatorio para proyectos públicos.

• Tienes acceso a tu servidor backend para implementar el endpoint de autenticación. El ejemplo de código de este artículo usa C#, pero los mismos principios se aplican a cualquier lenguaje del lado del servidor.

• Al menos un grupo de lectores está configurado en tu proyecto. El widget requiere al menos un ID válido de grupo lector para renderizar el contenido.

Habilitar y configurar JWT para el widget

Puedes implementar una configuración de autenticación para el widget usando JWT, asegurando un entorno seguro para proyectos privados y mixtos.

1. Navega a Conexiones (⊞) > al widget de la base de conocimientos en la barra de navegación izquierda.

   La lista de widgets aparecerá.

2. Pasa el cursor sobre el widget que quieres configurar y haz clic en el icono Editar (✎).

3. En la pestaña Configurar & conectar , navega hasta el acordeón JWT y activa el interruptor de Habilitar JWT.

1. ID del cliente: El ID del cliente será el ID de tu proyecto.

2. ID del widget: Dado que pueden existir varios widgets, se proporciona un ID de Widget para sus propósitos únicos.

3. Endpoint del token: Un punto final de token es un endpoint HTTP que te permite obtener un token de acceso dado un código de autorización.

4. Secreto del cliente: Haz clic en Regenerar para generar el secreto del cliente. Tienes que guardarlo para futuros fines, y el mismo secreto del cliente se aplicará a todos los widgets en el futuro.

NOTA
El secreto del cliente se comparte entre todos los widgets y chatbots compatibles con JWT del proyecto. Si regeneras el secreto, debes actualizar el nuevo secreto en todos los widgets y aplicaciones configurados por JWT para evitar fallos de autenticación.

El secreto del cliente solo se muestra durante la generación y no se almacena en Document360, así que guárdalo de forma segura.

e. Autorizar URL: Pegar la URL autorizada desde la página web de tu widget de base de conocimientos.

4. Haz clic en Guardar para aplicar cambios.

Incrusta la URL autorizada en tu código y pégala en la sección de scripts de tu página web. Esto implementará un widget seguro y autenticado que evitará accesos no autorizados de terceros.

NOTA

Habilitar JWT elimina el token de API del Widget Script. Si JWT se desactiva posteriormente, un nuevo token de API se regenera automáticamente y se restaura en el Widget Script.

Implementación del endpoint de autenticación

Después de configurar JWT en el portal, tendrás que configurar un endpoint de autenticación en tu aplicación backend. Este endpoint recibe una solicitud del widget y devuelve un token válido en respuesta.

El siguiente ejemplo muestra cómo implementar el endpoint en C#. La misma lógica se aplica a otros lenguajes de lado de servidor como Node.js o Python: adaptar el cliente HTTP y las librerías de serialización JSON según sea necesario.

/// <summary>
/// Endpoint to authenticate a user, generate a JWT token from Document360,
/// and return it to the widget.
/// </summary>
[HttpGet]
[Route("authenticate")]
public async Task<IActionResult> WidgetAuthentication(string id)
{
    // Ensure the user is authenticated in your application
    if (!HttpContext.User.Identity.IsAuthenticated)
    {
        return Unauthorized(new { message = "User is not authenticated." });
    }

    // Define configuration values
    var clientData = new ClientDetails
    {
        ClientId = "{Client ID}",                // Replace with your project's client ID
        Secret = "{Client secret}",              // Replace with your generated client secret
        TokenEndpoint = "{Token endpoint}",      // Replace with the token endpoint URL from Document360
        WidgetId = "{Widget ID}",                // Replace with your widget ID
        SecurityGroupIds = "group1,group2",      // Replace with comma-separated reader group IDs
        TokenValidity = 900                      // Token validity in seconds (300–86400)
    };

    // Return 404 if configuration is missing
    if (clientData == null)
    {
        return NotFound(new { message = "Client configuration not found." });
    }

    // Convert the comma-separated reader group IDs into a list
    List<string> readerGroupIds = null;
    if (!string.IsNullOrEmpty(clientData.SecurityGroupIds))
    {
        readerGroupIds = clientData.SecurityGroupIds
            .Split(',')
            .Select(c => c.Trim())
            .ToList();
    }

    // Prepare the payload with user and configuration details
    var payload = new
    {
        username = "{Username}",                     // Replace with actual user data if available
        firstName = "{First name}",
        lastName = "{Last name}",
        emailId = "{Email address}",
        readerGroupIds = readerGroupIds,
        tokenValidity = clientData.TokenValidity,
        widgetId = clientData.WidgetId,
        projectId = clientData.ClientId
    };

    var payloadString = JsonConvert.SerializeObject(payload);

    try
    {
        // Send request to Document360 token endpoint
        var result = await client.RequestTokenAsync(new TokenRequest
        {
            Address = clientData.TokenEndpoint,
            ClientId = clientData.ClientId,
            ClientSecret = clientData.Secret,
            GrantType = "Widget",
            Parameters = 
            {
                { "payload", payloadString },
                { "id", clientData.ClientId }
            }
        });

        // Return the access token to the widget
        return Ok(new
        {
            accessToken = result.AccessToken,
            expiresIn = result.ExpiresIn
        });
    }
    catch (Exception ex)
    {
        // Handle unexpected errors (optional)
        return StatusCode(500, new
        {
            message = "Failed to generate token.",
            details = ex.Message
        });
    }
}

• El tokenValidity valor se establece en segundos. Debe durar entre 300 segundos (5 minutos) y 86.400 segundos (1440 minutos). Si introduces un valor fuera de este rango, el sistema lo ajusta automáticamente al valor válido más cercano. Por ejemplo, si se ajusta tokenValidity a 60 segundos (1 minuto), el sistema lo aumenta hasta el valor mínimo permitido de 300 segundos (5 minutos). Un valor de 900 segundos (15 minutos) es un valor predeterminado razonable para la mayoría de los casos de uso: valores más cortos mejoran la seguridad pero aumentan la carga del backend.

• El widget requiere al menos un ID válido de grupo lector para renderizar el contenido. Incluye estos como una lista separada por comas en el readerGroupIds parámetro de la carga útil JWT.

Prueba la configuración de tu widget de JWT usando Postman

Después de configurar JWT en el portal Document360 e implementar tu endpoint de autenticación backend, puedes usar Postman para confirmar que tu configuración funciona como se espera.

Esta prueba simula lo que hace el widget: envía una petición a tu backend para obtener un JWT válido.

Prepara la prueba en Postman

1. Lanza Postman.

2. Selecciona + Nueva pestaña o haz clic en Nueva > petición HTTP.

3. Pon el método en POST.

4. En el campo de URL de solicitud, introduce la URL completa de tu endpoint backend.

   Ejemplo: https://yourdomain.com/authenticate

5. Ve a la pestaña de Autorización .

6. En Tipo, selecciona Autenticación Básica.

7. Introduce las siguientes credenciales:

   • Nombre de usuario: Tu ID de cliente del portal Document360.

   • Contraseña: Tu secreto de cliente (generado cuando creaste el JWT).

8. A continuación, para configurar el cuerpo de la solicitud, ve a la pestaña Cuerpo .

9. Selecciona en bruto.

10. Elige JSON en el desplegable de la derecha.

11. Pega el siguiente ejemplo de JSON en el cuerpo:

    {
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "john.doe@example.com",
      "readerGroupIds": ["group1", "group2"],
      "tokenValidity": 900,
      "widgetId": "your-widget-id",
      "projectId": "your-project-id"
    }

    Sustituye los valores por datos reales de tu app y configuración de Document360.

Si la solicitud tiene éxito, recibirás una respuesta JSON como la siguiente:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900
}

• accessToken: Este es el JWT firmado que el widget usará para autorizar al lector.

• expiresIn: Validez del token en segundos (15 minutos = 900 segundos).

Después de enviar la solicitud, comprueba que el estado de respuesta sea 200 OK, indicando que la solicitud ha sido exitosa. El cuerpo de la respuesta debe contener un , que accessTokenes el JWT con signo utilizado por el widget. Además, confirma que el expiresIn valor coincide con la duración esperada de validez del token en segundos (por ejemplo, 900 segundos durante 15 minutos).

Si todos estos valores aparecen correctamente, tu configuración JWT está funcionando como debe.

Resolución de problemas

Si la solicitud del cartero o el widget activo no devuelve un token válido, consulta los problemas comunes a continuación.

Próximos pasos

Después de verificar y funcionar tu configuración de JWT, puedes:

• Incrusta el widget en tu sitio web añadiendo el fragmento de script a la sección de scripts de tu página.

• Gestiona el acceso de los lectores actualizando las asignaciones de grupos de lectores en Conexiones > Lectores.

• Personaliza la apariencia y el comportamiento del widget desde la pestaña Personalizar del editor de widgets.