Configura JWT para el widget de la base de conocimiento

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.

Cómo funciona la autenticación JWT para el widget

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 maneja esto en silencio. Los lectores nunca ven una pantalla de inicio de sesión separada.

Usa JWT para el widget cuando:

• Tu base de conocimientos está restringida a usuarios o grupos de lectores específicos.
• Quieres acceso único al widget sin necesidad de un mensaje de inicio de sesión separado.
• Necesitas controlar qué contenido ve cada lector según su pertenencia al grupo.

Resumen del flujo de autenticación

El diagrama de flujo anterior muestra qué 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.

El diagrama de secuencia anterior 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).

Antes de que empieces

• Debes tener un rol de Propietario de Proyecto o Administrador en Document360.
• Al menos un widget de base de conocimiento debe existir ya. Si no, crea uno primero desde Conexiones > widget de la base de conocimientos. Más información en Añadir un widget.
• La visibilidad de tu base de conocimiento debe estar configurada como Privada o Mixta. JWT no es obligatorio para proyectos públicos.
• Debes tener 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.
• Debe haber al menos un grupo de lectores configurado en tu proyecto. El widget requiere al menos un ID válido de grupo lector para renderizar el contenido. Descubre más sobre los grupos de lectores de JWT.

Paso 1: Habilitar y configurar JWT para el widget

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

   Aparece la lista de widgets.

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

Se muestran los siguientes campos:

4. Haz clic en Guardar para aplicar los cambios.

Incrusta la URL autorizada en tu código y pégala en la sección de scripts de tu página web. Esto implementa un widget seguro y autenticado que evita el acceso no autorizado de terceros.

Paso 2: Implementar el endpoint de autenticación

Después de configurar JWT en el portal, configura un punto final 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 del lado del servidor como Node.js o Python.

/// <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}",
        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)
    {
        return StatusCode(500, new
        {
            message = "Failed to generate token.",
            details = ex.Message
        });
    }
}

Reglas de validez de los tokens:

• El tokenValidity valor se establece en segundos. El mínimo es de 300 segundos (5 minutos) y el máximo es de 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, poner tokenValidity a 60 segundos lo aumenta automáticamente a 300 segundos.
• 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.

Paso 3: Prueba la configuración de tu widget JWT usando Postman

Después de configurar JWT en el portal e implementar tu endpoint de autenticación backend, usa Postman para confirmar que tu configuración funciona como esperas. Esta prueba verifica que el endpoint backend de tu widget devuelva un token JWT válido.

1. Lanza Postman.

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

3. Configura 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. Ve a la pestaña de Cuerpo .

9. Selecciona raw y elige JSON en el desplegable.

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

11. Haz clic en enviar.

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

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

Verifica lo siguiente en la respuesta:

• El estado de respuesta es 200 OK.
• El cuerpo de respuesta contiene un archivo válido accessTokende .
• El expiresIn valor coincide con la duración esperada de validez de tu token en segundos.

Si los tres son correctos, la configuración de tu widget JWT está funcionando como debe.

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 Configuración > Usuarios y permisos > Lectores y grupos. Más información en gestión de grupos de lectores.
• Personaliza la apariencia y el comportamiento del widget desde la pestaña Personalizar del editor de widgets. Infórmate más sobre cómo personalizar el widget.

Mejores prácticas

• Guarda el secreto del cliente en un gestor de secretos seguro, no en archivos de código fuente o de entorno comprometidos con control de versiones.
• Ponlo tokenValidity tan corto como lo permita tu caso. Una validez más corta reduce la ventana de exposición si un token es interceptado.
• Siempre prueba con Postman antes de lanzarlo para detectar problemas de credenciales o cargas útiles antes de tiempo.
• Si regeneras el secreto del cliente, actualiza todos los widgets y chatbots que lo compartan antes de que los lectores comiencen su siguiente sesión. El secreto se comparte entre todos los widgets y chatbots compatibles con JWT del proyecto.
• Utiliza los IDs de grupos de lectores para imponer restricciones de contenido a nivel de token y que los lectores solo vean lo que están autorizados a acceder.

Preguntas frecuentes