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 luego 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 la visibilidad de tu base de conocimiento está configurada como Privada o Mixta. 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 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 de Document360 se comunica con tu sistema para obtener un token seguro antes de mostrar 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 conocimiento. Más información en Añadir un widget.
• La visibilidad de tu base de conocimientos 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 estar configurado al menos un grupo de lectores en tu proyecto. El widget requiere al menos un ID válido de grupo de lectores para renderizar el contenido. Infártese 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 de ajustes avanzados , navega hasta el acordeón JWT y activa el interruptor de 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 impide el acceso no autorizado de terceros.

Paso 2: Implementar el endpoint de autenticación

Después de configurar JWT en el portal, configura 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 ejemplo siguiente muestra cómo implementar el endpoint en C#. Utiliza el RequestTokenAsync método de extensión de la biblioteca IdentityModel. La misma lógica se aplica a otros lenguajes del lado del servidor como Node.js o Python.

using IdentityModel.Client;

/// <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 to 86400)
    };

    // 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
    {
        // Create an HttpClient instance. In production, reuse a single instance
        // (for example, through IHttpClientFactory) instead of creating one per request.
        using var client = new HttpClient();

        // 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 300 segundos (5 minutos) y el máximo es 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 en 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 se espera. Esta prueba verifica que el endpoint backend de tu widget devuelva un token JWT válido.

1. Lanza Postman.

2. Selecciona + Pestaña Nuevo o haz clic en Nueva > solicitud 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.

Abrir artículos widget en la página de la base de conocimiento

Cuando un lector hace clic en el icono Abrir en nueva pestaña dentro del widget, el artículo se abre en tu sitio de la base de conocimientos. El widget y el sitio de la base de conocimientos utilizan sesiones JWT separadas, por lo que la sesión del widget del lector no los inicia sesión en el sitio.

Si tu base de conocimientos tiene varias configuraciones de JWT, el sitio no puede determinar qué inicio de sesión JWT debe usar el lector, y el lector ve la página general de inicio de sesión.

Para llevar a los lectores directamente al artículo, inicia sesión en la base de conocimientos desde tu propia aplicación y redirígelos a la ruta del artículo. Para el formato de URL, consulta Redirigir a una página específica tras iniciar sesió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 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 el panel de Apariencia , en la pestaña Instalación y Configuración del editor de widgets. Aprende 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.
• Configura tokenValidity lo más corto que permita tu caso de uso. 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 en el 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