Creación de JWT SSO

¿Qué es un JWT?

Un JSON Web Token (JWT) es un formato de token cifrado que transfiere de forma segura datos, como credenciales de autenticación y autorización, entre dos aplicaciones. En Document360, JWT se utiliza para autenticar los inicios de sesión de los lectores.  Haz clic aquí para leer sobre JWT.

Document360 utiliza un enfoque similar al PKCE (Proof Key for Code Exchange, un método OAuth seguro) para generar el token JWT.

SSO empresarial usando JWT en Document360

Document360 soporta JWT como uno de sus métodos SSO (Single Sign-On) para autenticar los inicios de sesión de los lectores. Proporciona una forma segura de transferir datos de autenticación y autorización entre tu aplicación y tu base de conocimientos Document360Knowledge base.

Puedes crear hasta 5 configuraciones de JWT por proyecto. Hasta 3 de ellos pueden aparecer como botones de inicio de sesión en la página orientada al lector. Si tienes más de 3, los lectores aún pueden acceder a las configuraciones restantes escribiendo su nombre de dominio en el campo de entrada de nombre de dominio en la página de inicio de sesión.

JWT también trabaja junto a proveedores SSO como SAML y OpenID, puedes tener a todos activos en el mismo proyecto al mismo tiempo.

Elegir el método SSO adecuado: JWT vs SAML vs OpenID

Document360 soporta tres opciones SSO para la autenticación de lectores: JWT, SAMIL y OpenID Connect. Elegir el método adecuado depende de cómo gestiones a los usuarios, qué infraestructura ya tienes y cuánto control necesitas sobre el proceso de inicio de sesión.

La siguiente tabla compara JWT con las otras opciones:

Cómo funciona la autenticación JWT

El diagrama general a continuación muestra cómo lograr el flujo de autenticación JWT en Document360.

Los pasos siguientes explican el flujo completo de autenticación JWT en Document360 para desarrolladores que configuran el SSO de lectores usando su propio sistema de inicio de sesión.

Terminología clave

Flujo de autenticación

1. El usuario accede a la base de conocimiento privada

   • Cuando un usuario intenta acceder a tu base de conocimientos, Document360 detecta que JWT SSO está activado y redirige al usuario a la URL de inicio de sesión configurada en la configuración de JWT.

2. El usuario inicia sesión en tu aplicación

   • Si el usuario no está ya autenticado, tu página de inicio de sesión se encarga de su autenticación.

3. Tu backend solicita un código de autenticación de un solo uso

   • Después de que el usuario inicia sesión, tu backend envía una POST solicitud a la URL de generación de código configurada en Document360 con lo siguiente:

     • Identidad de usuario (por ejemplo, nombre, correo electrónico)

     • Opcional readerGroupIds

     • tokenValidity en minutos

   • Esta solicitud debe estar autorizada usando HTTP Basic Auth con tu ID de cliente y secreto del cliente.

Cabecera de autorización de ejemplo

Authorization: Basic Base64Encode(clientId:clientSecret)

Ejemplo de carga útil JSON

{
  "username": "firstname + lastname",
  "firstName": "firstname",
  "lastName": "lastname",
  "emailId": "user email",
  "readerGroupIds": ["Obtain from Reader groups overview page in the Document360 portal (Optional)"],
  "tokenValidity": 15 //minutes
}

NOTA

Asegúrate de que la sintaxis JSON sea correcta para evitar errores de configuración.

4. El servidor Document360 Identity devuelve un código de autenticación

   • Si la solicitud es válida, el servidor de identidad de Document360 genera un código de autorización de un solo uso y lo envía de vuelta a tu aplicación (backend).

5. Tu aplicación redirige al usuario de vuelta a Document360

   • Tu backend añade el código a la URL de Callback y redirige al usuario hacia ella.

   • Por ejemplo: https://yourproject.document360.io/jwt/authorize?code=xyz

NOTA

El código de autenticación es un código de un solo uso y no puede reutilizarse.

6. Document360 valida el código

   • Una vez que recibe el código, Document360 lo envía al servidor de identidad a través de un backchannel para intercambiarlo por un token JWT.

7. Se crea la sesión de lectura

   • Document360 extrae información del usuario y reglas de acceso (basadas en readerGroupIds) del token.

   • Se crea una sesión para el lector, dándole acceso a categorías, idiomas o versiones permitidas.

Validez del token y comportamiento de la sesión

• Puedes definir la duración de la sesión usando el tokenValidity campo de la carga útil (mínimo: 5 minutos, máximo: 1440).

• Una vez que el token expira:

  • El lector es redirigido de nuevo a tu URL de inicio de sesión.

  • Si el usuario sigue autenticado en tu app, se genera un nuevo código y la sesión se restablece sin problemas.

Configuración JWT en Document360

Configura la autenticación JSON Web Token (JWT) para permitir que los lectores inicien sesión de forma segura usando tokens de tu aplicación o proveedor de identidad. Puedes crear hasta 5 configuraciones de JWT por proyecto, con hasta 3 que se muestran como botones de inicio de sesión en la página del lector para acceso rápido. Opciones adicionales de JWT siguen siendo accesibles a través del campo Nombre de dominio. JWT funciona de forma fluida junto a proveedores SSO como SAML y OpenID, permitiendo que múltiples métodos de autenticación coexistan en el mismo proyecto.

Para acceder a la página de JWT, navega a Configuración > Usuarios y permisos > JWT.

Nuevo en JWT en Document360

Si no existe ninguna configuración JWT en tu proyecto, completa los siguientes pasos en orden:

1. Configurar el inicio de sesión en JWT — configurar configuraciones compartidas a nivel de proyecto.

2. Crea una configuración JWT — añade tu primera configuración JWT.

3. Configura tu solicitud — conecta tu solicitud a Document360.

Configuraciones adicionales de JWT y proveedores SSO (SAML u OpenID) pueden añadirse al mismo proyecto en cualquier momento sin afectar a las configuraciones existentes.

Configuración existente de JWT

Si configuras JWT antes de junio de 2026, tu configuración actual aparece en una vista de solo lectura. Tu configuración actual de JWT permanece activa y los lectores pueden seguir iniciando sesión sin interrupciones.
Cuando navegas a Configuración > Usuarios y Permisos > JWT, puedes:

• Sigue usando la configuración: No se requieren cambios.

• Editar la configuración: Haz clic en el icono Editar para actualizar la configuración.

• Elimina la configuración: Haz clic en el icono de Borrar para eliminarla.

Añadir otra configuración JWT

Haz clic en Crear JWT para añadir una nueva configuración. Sigue configurando inicio de sesión en JWT y crea configuración JWT para crear configuraciones adicionales de JWT. Un proyecto puede tener hasta 5 configuraciones JWT. Tras guardar, la página cambia a la vista de lista y muestra todas las entradas JWT configuradas. Tu configuración actual permanece sin cambios

Configurar SSO junto a JWT

Ve a Configuración > Usuarios y Permisos > Configuración SSO y configura tu proveedor SSO. Tu configuración de JWT no se ve afectada en absoluto. Ambos estarán activos al mismo tiempo y los lectores verán ambas opciones en la página de inicio de sesión. Consulta la coexistencia entre JWT y SSO para más detalles sobre cómo es la página de inicio de sesión.

Paso 1 — Configurar el inicio de sesión en JWT

Haz clic en Configurar inicio de sesión JWT en el banner de la página de JWT para abrir el modal de configuración.

Autenticación

Estos son valores de solo lectura generados por Document360. Cópialos usando el botón Copiar y configúralos en tu proveedor de identidad.

Otros escenarios

Inicio de sesión directo en JWT

Por defecto: ON

• Cuando está activado, los lectores son redirigidos directamente a iniciar sesión en JWT sin que se les muestre una pantalla de selección de inicio de sesión. Esto es apropiado cuando JWT es el único método de autenticación para tu base de conocimiento.

• Cuando está desactivado, los lectores muestran una pantalla de selección de inicio de sesión que muestra todas las opciones configuradas de inicio de sesión — JWT, SSO y el inicio de sesión predeterminado de Document360. Desactiva esta configuración cuando hay varios métodos de autenticación activos y los lectores deben elegir su método de inicio de sesión. Se requiere una confirmación antes de aplicar este cambio.

• Cuando se configuran varias configuraciones JWT y SSO, pero el propietario del proyecto quiere que los lectores inicien sesión solo mediante autenticación JWT, pueden habilitar el inicio de sesión Direct JWT.

Desactivar la página de inicio de sesión por defecto

Por defecto: DESACTIVADO

• Cuando está activado, el inicio de sesión estándar de correo electrónico y contraseña de Document360 queda oculto. Los lectores solo pueden autenticarse a través de proveedores configurados de JWT o SSO. Esto se utiliza típicamente en entornos empresariales donde todo el acceso de los lectores debe controlarse mediante un sistema centralizado de identidade.

   NOTA

  Activa esta configuración solo después de que la autenticación JWT o SSO haya sido completamente configurada y probada. Si el proveedor externo de autenticación está mal configurado, los lectores no podrán acceder a la base de conocimiento.

Haz clic en Cerrar para descartar el modal. Los cambios se aplican de inmediato.

Paso 2 — Crear una configuración JWT

En la página de JWT, haz clic en Crear JWT en la esquina superior derecha. Se abre el modal Create JWT .

Nombre

Introduce un nombre descriptivo para identificar esta configuración, por ejemplo, SSO del Portal del Cliente. Este nombre aparece en la lista JWT en el portal. Si el botón de inicio de sesión está activado, este nombre también se muestra a los lectores en la página de inicio de sesión, por lo que debería tener sentido para la audiencia que inicia sesión.

Autenticación

Reglas de validación de nombres de dominio:

• Los subdominios se tratan como entradas distintas. portal.example.com y example.com son dominios separados y pueden asignarse a diferentes configuraciones.

• Dominios comodines como *.example.com no son compatibles. Cada dominio debe tener un valor exacto.

• Un dominio ya asignado a otra configuración JWT en el mismo proyecto no puede ser reutilizado. En la partida guardada aparece un error de validación en línea.

Claves JWT

IMPORTANTE

Las fichas secretas se muestran solo una vez en el momento de la creación. Cópialos y guárdalos de forma segura antes de cerrar el modal. Si se pierden, deben regenerarse, lo que invalida inmediatamente los tokens anteriores.

Document360 genera automáticamente dos tokens secretos cuando se abre el modal. Estos tokens solo son visibles en texto plano durante esta sesión. Una vez que el modal está cerrado, se enmascaran y no pueden recuperarse.

Utiliza el icono de Copiar junto a cada token para copiar su valor.

Ajustes avanzados

Expande la configuración avanzada para configurar las siguientes opciones.

Habilitar la autenticación JWT

Por defecto: ON

• Cuando está activada, esta configuración está activa y los lectores pueden usarla para iniciar sesión. Desactivarlo desactiva la configuración sin eliminarla, lo cual es útil para suspender temporalmente una configuración sin perder sus ajustes.

Botón de mostrar inicio de sesión

Por defecto: DESACTIVADO

Cuando está activada, aparece un botón de inicio de sesión con marca para esta configuración en la página de inicio de sesión de la base de conocimientos. Esto ofrece a los lectores una opción de inicio de sesión directo sin necesidad de introducir un nombre de dominio.

 NOTA

Se pueden mostrar un máximo de 3 botones de inicio de sesión de JWT simultáneamente en la página de inicio. Cuando se alcanza este límite, el interruptor se desactiva automáticamente para configuraciones adicionales. Los lectores asignados a configuraciones sin un botón visible aún pueden autenticarse introduciendo su nombre de dominio en el campo Nombre de dominio de la página de inicio de sesión, lo que les encamina a la configuración correcta.

Cuando el botón de mostrar inicio de sesión está activado, están disponibles los siguientes campos adicionales:

• Texto del botón de inicio de sesión — la etiqueta que aparece en el botón Esto debería identificar claramente la fuente de autenticación para los lectores.

• Logotipo del botón de inicio de sesión — una imagen subida para marcar el botón. Formatos aceptados: JPG, PNG, SVG Tamaño máximo de archivo: 512 KB.

Paso 3 — Configura tu solicitud

Copia los siguientes valores de la configuración JWT y añádelos a los campos correspondientes en tu aplicación cliente:

• ID de cliente

• URL de devolución de llamada

• URL de generación de código

• Ficha secreta principal

• Ficha secreta secundaria

Guardar la configuración

Haz clic en Crear. El botón permanece inactivo hasta que todos los campos requeridos contengan valores válidos. En caso de éxito, el modal se cierra y la nueva configuración aparece en la lista JWT.

 NOTA

Los lectores no necesitan una cuenta Document360 separada. La autenticación se gestiona íntegramente a través de tu aplicación. Una cuenta en tu aplicación es suficiente para que un lector acceda a la base de conocimientos

Lista de comprobación para desarrolladores

• Registra la URL de Inicio de Sesión, la URL de Llamada y la URL de generación de código en la configuración de tu JWT.

• Guarda el secreto del cliente de forma segura. Solo se muestra una vez en el momento de su creación.

• Implementa lógica backend para llamar a la URL de generación de código usando HTTP Basic Auth.

• Firma el JWT en tu backend usando tu secreto de cliente. Nunca expongas la lógica de signos en el lado del cliente.

• Aplica HTTPS en todos los endpoints implicados en el flujo de autenticación.

• Comportamiento de prueba en la sesión, vencimiento del token y renovación automática de la sesión antes de que se active.

• Monitoriza los registros del backend en busca de errores 401, que normalmente indican códigos de autorización caducados o discrepancias de tokens.

Implementación de la lógica de redirección SSO de JWT

Tras completar la configuración de JWT en Document360, tu aplicación necesita una ruta backend para gestionar el paso final del flujo de inicio de sesión.

Esta ruta:

• Valida que el usuario ya está autenticado en tu aplicación

• Envía una solicitud segura a la URL de generación de código de Document360

• Recupera un código de autorización de un solo uso

• Redirige al usuario al sitio de la base de conocimientos con ese código

     /// <summary>
     /// Example endpoint to authenticate a user and retrieve a token from the identity server,
     /// and redirect the user to the Knowledge Base (KB) using the token code.
     /// </summary>
     /// <param name="clientId">Client ID issued for your application</param>
     /// <param name="clientSecret">Client secret associated with the client ID</param>
     /// <returns>Redirects to the KB with the issued code</returns>
     [HttpGet]
     [Route("authenticate")]
     public async Task<IActionResult> AuthenticateAsync(string clientId, string clientSecret)
     {
         if (!HttpContext.User.Identity.IsAuthenticated)
         {
             // user is not authenticated, redirect to an error or login page
             return Unauthorized(new { message = "User not authenticated" });
         }

         // Ensure you have the correct client ID and secret from your Document360 JWT configuration
         var authToken = Encoding.ASCII.GetBytes($"{clientId}:{clientSecret}");

         // Create an HttpClient instance
         using var httpClient = new HttpClient();

         // Set the Authorization header with Basic authentication
         httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(authToken));

         // Prepare the payload with user information
         var payload = new
         {
             username = User.Identity.Name,
             firstName = "FirstName", // Replace or customize as needed
             lastName = "LastName",
             emailId = "user@example.com", // Replace with actual user email
             readerGroupIds = new List<string> { "group1", "group2" }, // Replace with actual reader group IDs if needed (Optional)
             tokenValidity = 3600 // Token validity in seconds (Optional, default is 5 minutes)
         };

         var payloadContent = new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");

         // Identity server token endpoint - replace with your actual URL
         string identityServerUrl = "codeGeneration endpoint, you can find that in JWT config portal";
         // KB login URL to redirect after successful token issuance
         string kbLoginUrl = "https://{your subdomain}.document360.io";

         var response = await httpClient.PostAsync(identityServerUrl, payloadContent);

         if (response.IsSuccessStatusCode)
         {
             var content = await response.Content.ReadAsStringAsync();
             var tokenJson = JObject.Parse(content);
             // Extract the code from the response
             var tokenCode = (string)tokenJson.SelectToken("code");

             // Construct the KB login URL with code query parameter
             string finalRedirectUrl = $"{kbLoginUrl}?code={tokenCode}";

             return Redirect(finalRedirectUrl);
         }
         else
         {
             // Handle error response from the identity server
             var error = await response.Content.ReadAsStringAsync();
             return StatusCode((int)response.StatusCode, new { error = "Token request failed", details = error });
         }
     }

const express = require('express');
const https = require('https');
const axios = require('axios');
const app = express();

// Middleware to parse JSON
app.use(express.json());

// Replace with your actual client ID and secret from Document360
const clientId = 'b20bf794-050c-4194-bc30-bd834c51adad';
const clientSecret = '07U7nXLbOY7-klsmWrOOT3_qHa631XMOuqSd_gl69I8';
const codeGenerationUrl = 'https://identity.document360.net/jwt/generateCode';
// Your D360 KB URL (Replace your-subdomain)
const kbLoginUrl = 'https://jwt-readergroup1-sep.document360.net/jwt/authorize';

// ROUTE: /authenticate
app.get('/authenticate', async (req, res) => {
  try {
    // Example — add your real auth logic
    const isAuthenticated = true;

    if (!isAuthenticated) {
      return res.status(401).json({ message: 'User not authenticated' });
    }

    // Basic Authorization header
    const authHeader = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

    // Payload to send to D360
    const payload = {
      username: 'john.doe',
      firstName: 'John',
      lastName: 'Doe',
      emailId: 'john.doe@example.com',
      readerGroupIds: ['group1', 'group2'],
      tokenValidity: 3600
    };

    // POST to D360 identity server to get the code
    const response = await axios.post(
      codeGenerateUrl,
      payload,
      {
        headers: {
          'Authorization': `Basic ${authHeader}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        httpsAgent: new https.Agent({ maxVersion: 'TLSv1.2' })
      }
    );

    const tokenCode = response.data?.code;

    if (!tokenCode) {
      return res.status(500).json({ message: 'No code received from Document360' });
    }

    console.log("Redirecting to:", `${kbLoginUrl}?code=${tokenCode}`);
    // Redirect user to KB with ?code=<token>
    return res.redirect(`${kbLoginUrl}?code=${tokenCode}`);

  } catch (error) {
    console.error("JWT SSO error:", error.message);

    return res.status(500).json({
      message: "JWT SSO failed",
      details: error.response?.data || error.message
    });
  }
});

import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

import java.nio.charset.StandardCharsets;
import java.util.*;

@RestController
public class JwtSsoController {

    private final String clientId = "your-client-id";
    private final String clientSecret = "your-client-secret";
    private final String codeGenerationUrl = "https://identity.document360.io/api/jwt/generate-code";
    private final String kbLoginUrl = "https://your-subdomain.document360.io/jwt/authorize";

    @GetMapping("/authenticate")
    public ResponseEntity<?> authenticate() {
        // Example: Check if user is authenticated in your system
        boolean isAuthenticated = true; // Replace with actual logic
        if (!isAuthenticated) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("User not authenticated");
        }

        // Create Basic Auth header
        String auth = clientId + ":" + clientSecret;
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes(StandardCharsets.UTF_8));
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Authorization", "Basic " + encodedAuth);
        headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

        // Construct payload
        Map<String, Object> payload = new HashMap<>();
        payload.put("username", "john.doe");
        payload.put("firstName", "John");
        payload.put("lastName", "Doe");
        payload.put("emailId", "john.doe@example.com");
        payload.put("readerGroupIds", Arrays.asList("group1", "group2"));
        payload.put("tokenValidity", 3600); // Optional

        HttpEntity<Map<String, Object>> request = new HttpEntity<>(payload, headers);
        RestTemplate restTemplate = new RestTemplate();

        try {
            ResponseEntity<Map> response = restTemplate.postForEntity(codeGenerationUrl, request, Map.class);

            if (response.getStatusCode() == HttpStatus.OK && response.getBody() != null) {
                String tokenCode = (String) response.getBody().get("code");

                if (tokenCode == null || tokenCode.isEmpty()) {
                    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                            .body("No code returned from Document360");
                }

                // Redirect to the KB site with code
                String redirectUrl = UriComponentsBuilder.fromHttpUrl(kbLoginUrl)
                        .queryParam("code", tokenCode)
                        .toUriString();

                HttpHeaders redirectHeaders = new HttpHeaders();
                redirectHeaders.setLocation(java.net.URI.create(redirectUrl));
                return new ResponseEntity<>(redirectHeaders, HttpStatus.FOUND); // 302 redirect

            } else {
                return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
                        .body("Failed to get code from Document360: " + response.getStatusCode());
            }

        } catch (Exception ex) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("JWT SSO error: " + ex.getMessage());
        }
    }
}

Probando tu configuración de JWT

Una vez que hayas implementado la lógica SSO de JWT en tu backend, puedes probar la integración usando cualquiera de cURL los dos o Postman. Estas pruebas simulan cómo tu backend se comunica con el servidor de identidad de Document360 para recuperar un código de autorización de un solo uso.

Probando la configuración de JWT usando cURL

curl -X POST https://identity.document360.io/api/jwt/generate-code \
  -H "Authorization: Basic BASE64_ENCODED_CLIENTID:CLIENTSECRET" \
  -H "Content-Type: application/json" \
  --http2-prior-knowledge \
  --tls-max 1.2 \
  -d '{
        "username": "john.doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailId": "john.doe@example.com",
        "readerGroupIds": ["group1", "group2"],
        "tokenValidity": 15
      }'

Tras habilitar el inicio de sesión en JWT, el lector puede usar la aplicación cliente para iniciar sesión como cuenta lectora en la base de conocimientos Document360.

Probando la configuración de JWT usando Postman

Puedes probar tu configuración SSO de JWT usando Postman enviando manualmente una solicitud a la URL de generación de código. Esto te permite verificar que las credenciales y la carga útil de tu cliente han sido aceptadas y que se ha generado correctamente un código de autorización de un solo uso.

Para probar usando Postman, sigue estos pasos:

1. Abre Postman y crea una nueva solicitud.

   Configura el método de solicitud en POST y, en el campo URL, introduce la URL de generación de código desde la pantalla de configuración JWT:

   https://identity.document360.io/api/jwt/generate-code

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

3. Establece el Tipo en Basic Auth.

4. En el campo Nombre de usuario , introduce tu ID de cliente.

5. En el campo Contraseña , introduce tu Secreto del Cliente.

6. Navega a la pestaña Cuerpo .

7. Selecciona la opción raw y pon el formato en JSON.

8. Introduce la carga útil JSON requerida. Ejemplo:

   {
     "username": "john.doe",
     "firstName": "John",
     "lastName": "Doe",
     "emailId": "john.doe@example.com",
     "readerGroupIds": ["group1", "group2"],
     "tokenValidity": 15
   }

9. Haz clic en Enviar para enviar la solicitud.

Si la configuración es correcta, deberías recibir una 200 OK respuesta con un único code. Luego puedes usar este código para redirigir al lector al sitio de la base de conocimientos y completar el flujo de inicio de sesión SSO.

Enrutamiento de lectores basados en dominio

Cuando un lector introduce un dominio en el campo de nombre de dominio de la página de inicio de sesión, Document360 lo compara con todas las configuraciones JWT activas y enruta al lector a la URL de inicio de sesión de la configuración correspondiente.

Document360 aplica una regla de coincidencia más específica. Por ejemplo, si tanto example.com como support.example.com están configurados, un lector que introduce support.example.com es enrutado a la support.example.com configuración en lugar del dominio padre. Esto permite que los subdominios sean gestionados por configuraciones dedicadas sin conflicto.

Reglas adicionales de enrutamiento:

• La coincidencia de dominio no distingue a mayúsculas y minúsculas, y cada nombre de dominio debe ser único.

• Si la configuración emparejada está inactiva, el lector se dirige a las opciones predeterminadas de inicio de sesión.

• Si no se encuentra ninguna coincidencia, el lector es dirigido a las opciones predeterminadas de inicio de sesión.

• El campo Nombre de dominio se aplica exclusivamente al enrutamiento JWT. No se puede acceder a los proveedores SSO a través de este campo.

Coexistencia entre JWT y SSO

Las configuraciones JWT y SSO (SAML u OpenID) pueden estar activas simultáneamente en el mismo proyecto. Cada tipo se gestiona de forma independiente: modificar una configuración JWT no afecta a las configuraciones SSO, y viceversa. Esto permite a las organizaciones apoyar a lectores de diferentes sistemas de identidad a través de un único portal de base de conocimiento sin ningún conflicto entre métodos de autenticación.

Por ejemplo, los clientes empresariales pueden autenticarse mediante un sistema basado en JWT vinculado a tu aplicación, mientras que los miembros internos del equipo inician sesión mediante un IdP centralizado como Okta usando SAML. Ambos métodos pueden estar activos al mismo tiempo sin interferencias.

Límites de botones de inicio de sesión

Por ejemplo, si 5 configuraciones JWT están activas, 3 aparecen como botones de inicio de sesión y los 2 restantes solo son accesibles mediante entrada de dominio. Si 6 configuraciones SSO están activas, solo 5 son accesibles — la sexta no puede ser accesible por los lectores.

El límite JWT (3) y el límite SSO (5) se aplican de forma independiente. Alcanzar un límite no afecta al otro.

Cuando se alcanza el límite de 3 botones para JWT, todos los administradores del proyecto reciben una notificación del sistema: "Has alcanzado el límite de 3 botones de inicio de sesión en JWT. Las configuraciones adicionales de JWT no aparecerán como botones en la página de inicio de sesión. Los lectores aún pueden iniciar sesión introduciendo su nombre de dominio."

Estados de la página de inicio de sesión del lector

La página de inicio de sesión que se presenta a los lectores está determinada por dos factores: el estado del interruptor de la página de inicio de sesión por defecto y qué configuraciones de JWT y SSO están activas actualmente.

Normas aplicables:

• Solo se muestran configuraciones activas. Las configuraciones inactivas nunca se muestran a los lectores independientemente del estado del interruptor.

• El campo de entrada de nombre de dominio se muestra siempre que el interruptor está ACTIVADO y al menos una configuración JWT está activa. Esto garantiza que las configuraciones JWT sin un botón de inicio de sesión visible permanezcan accesibles mediante la entrada de dominio.

• Si todas las configuraciones JWT y SSO están inactivas mientras el interruptor está ACTIVADO, a los lectores se les muestra un mensaje que indica que actualmente no hay opciones de inicio de sesión disponibles.

• Los cambios en el estado de desactivación o el estado de configuración entran en vigor inmediatamente para nuevas sesiones de lectores. Las sesiones autenticadas existentes no se ven afectadas.

Registro y notificaciones de auditoría

Todas las acciones de configuración de JWT se capturan automáticamente en el registro de auditoría. Esto proporciona un registro completo e inviolable de los cambios para fines de cumplimiento y revisión de seguridad.

Acciones registradas:

• Crear, actualizar, eliminar

• Activar, Desactivar

• Regenerar Token Primario, Regenerar Token Secundario

• Activar/Desactivar el inicio de sesión directo de JWT

• Activar/Desactivar la página de inicio de sesión por defecto

Cada entrada de registro registra el tipo de acción, la marca de tiempo (UTC), la identidad del administrador que realizó la acción y el nombre de configuración en el momento de la acción. Para las acciones de actualización, el registro captura los campos específicos que cambiaron junto con los valores anteriores y nuevos. Los valores de los tokens nunca se registran — solo se registra el hecho de la rotación para proteger la seguridad de las credenciales.

Los registros se conservan durante un mínimo de 90 días. El acceso a los registros de auditoría de JWT está restringido a usuarios con permisos de Seguridad y Auditoría.

Para habilitar el seguimiento de actividad JWT en Auditoría de Equipos, navega a Configuración > Seguridad y Auditoría > Configuración de auditoría > Auditoría de equipo y activa los interruptores de eventos JWT correspondientes. Una vez habilitada, la actividad de JWT se registra en la pestaña de auditoría del equipo. Utiliza el desplegable de Evento y busca "JWT" para filtrar los registros por tipo de evento.

Destinatarios de notificaciones por correo electrónico:

Redirección a otras páginas en lugar de la página principal

Por defecto, tras iniciar sesión, los usuarios son redirigidos a la página principal de tu base de conocimientos.

• Si tu página principal no está publicada, los usuarios serán redirigidos a la página /docs .

• Para redirigir a los usuarios a una página diferente en tu base de conocimientos (aparte de las páginas de inicio o /docs ), configura la redirección durante la configuración de JWT usando el siguiente código.

Patrón de URL

https://<Knowledge base URL>/jwt/authorize?code=<code>&redirectUrl=<redirect path>

Parámetros

• <URL de la base de conocimiento>: La URL principal de tu sitio de base de conocimientos.

• <Código>: El código generado por el endpoint de generación de código de Document360.

• <ruta de redirección>: La nueva URL donde quieres que los usuarios aterrizan tras iniciar sesión.

Ejemplo

https://example.document360.io/jwt/authorize?code=FOTaS_SW6dLGytQXvrG_rRFGhyPvrDDrgxJAZzYvJcY&redirectUrl=/docs/5-basic-things-to-get-started

NOTA

• Document360 enviará la URL de Redirección al redirectPath punto final de inicio de sesión. Cuando el punto final de inicio de sesión redirige de nuevo a la base de conocimientos con el código de autenticación, debería devolver la URL de Redirección como redirectUrl parámetro.

• En KB Site 2.0, la redirección se gestiona mediante cookies en lugar del redirectUrl parámetro. Si tu implementación en JWT se basa en la redirección de cadenas de consulta (usando el redirectUrl parámetro), ten en cuenta que el enfoque basado en cookies no soporta este parámetro. Puede que necesites actualizar tu implementación o contactar con el soporte para aclarar más.

Resolución de problemas

Si encuentras problemas durante la configuración SSO de JWT, consulta los siguientes errores comunes y sus soluciones:

Error 401 no autorizado al probar JWT en Postman

Error: 401 Error no autorizado

Si te encuentras con un error no autorizado 401 al probar JWT (JSON Web Token) usando Postman, esto suele ocurrir porque la configuración de autorización no está configurada correctamente.

Pasos para resolver:

Para resolver este error,

1. En Postman, abre la solicitud que estás probando.

2. Navega a la pestaña de Autorización .

3. Establece el tipo de autorización en Autenticación Básica.

4. En el campo Nombre de usuario , introduce el ID del cliente.

5. En el campo Contraseña , introduce el Secreto del Cliente.

6. Ve a la pestaña de Cuerpo .

7. Selecciona la opción en RAW en el desplegable y asegúrate de que el formato esté configurado en JSON.

8. Añade la carga útil JSON requerida para la solicitud de la API.

9. Haz clic en Enviar para ejecutar la solicitud.

Consulta la respuesta para ver los resultados esperados. Si la solicitud tiene éxito, deberías recibir un código o token de autenticación en la respuesta.