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 funciona la autenticación JWT para widgets
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:
El usuario visita tu sitio web, donde está incrustado el widget de Document360.
El widget envía una solicitud silenciosa a tu endpoint de autenticación (endpoint de token) configurado en la configuración del widget.
Tu backend envía una solicitud a Document360 con las credenciales requeridas (ID del cliente, secreto del cliente) y los detalles del lector.
Document360 valida la solicitud y devuelve un JWT firmado a tu backend.
Tu backend envía el token de vuelta al widget.
El widget utiliza este token para obtener y mostrar artículos a los que el lector tiene acceso.
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.
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.
Navega a Conexiones () > al widget de la base de conocimientos en la barra de navegación izquierda.
La lista de widgets aparecerá.
Pasa el cursor sobre el widget que quieres configurar y haz clic en el icono Editar ().
En la pestaña Configurar & conectar , navega hasta el acordeón JWT y activa el interruptor de Habilitar JWT.
ID del cliente: El ID del cliente será el ID de tu proyecto.
ID del widget: Dado que pueden existir varios widgets, se proporciona un ID de Widget para sus propósitos únicos.
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.
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 será necesario para los widgets JWT que puedas crear. Ten en cuenta que esta información no se almacenará en Document360.
e. Autorizar URL: Pegar la URL autorizada desde la página web de tu widget de base de conocimientos.
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.
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#.
/// <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 = 15 // Token validity in minutes (5–1440)
};
// 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
});
}
}NOTA
El
tokenValidityvalor se fija en minutos. Debe durar entre 5 minutos (300 segundos) y 1440 minutos (86.400 segundos). Si introduces un valor fuera de este rango, el sistema lo ajusta automáticamente al valor válido más cercano. Por ejemplo, si lo ponestokenValidityen 1 minuto (60 segundos), el sistema lo aumenta hasta el valor mínimo permitido de 5 minutos (300 segundos).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
readerGroupIdspará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
Lanza Postman.
Selecciona + Pestaña Nuevo o haz clic en Nueva > solicitud HTTP.
Pon el método en POST.
En el campo de URL de solicitud, introduce la URL completa de tu endpoint backend.
Ejemplo:
https://yourdomain.com/authenticateVe a la pestaña de Autorización .
En Tipo, selecciona Autenticación Básica.
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).
A continuación, para configurar el cuerpo de la solicitud, ve a la pestaña Cuerpo .
Selecciona en bruto.
Elige JSON en el desplegable de la derecha.
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": 15, "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.