Creación de JWT SSO

¿Qué es un JWT?

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

SSO empresarial usando JWT en Document360

Document360 soporta JWT (JSON Web Token) como uno de sus métodos SSO (Single Sign-On), utilizado principalmente para autenticar los inicios de sesión de los lectores. JWT proporciona una forma segura de transferir datos de autenticación y autorización entre tu aplicación y la base de conocimientos Document360.

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

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:

Configuración JWT en Document360

Antes de implementar JWT SSO, primero debes configurar el JWT en Document360 y obtener las credenciales necesarias.

Creando un JWT

Para crear un JSON Web Token (JWT),

1. Inicia sesión en el portal Document360.

2. Ve a Configuración ()> Usuarios y permisos > JWT.

3. Crea un JWT (secreto del cliente) desde aquí haciendo clic en el botón Crear JWT .

4. Copia el secreto del cliente generado haciendo clic en el icono de copiar y en Cerrar.

NOTA

El mismo secreto del cliente generado no estará disponible cuando vuelvas a esta sección. Si es necesario, el secreto del cliente debe regenerarse.

La página de configuración de JWT con todos los datos ya está disponible.

Resumen de la página de configuración de JWT

Después de crear un JWT, la página de configuración del JWT será visible.

• Configura tu solicitud: Copia el ID del cliente, la URL de devolución de llamada, la URL de generación de código, el secreto del cliente y pégalos en los campos correspondientes de la aplicación cliente

• Estado JWT: Activa o desactiva el inicio de sesión SSO de JWT para lectores usando este interruptor. Si el interruptor está desactivado, los lectores no podrán iniciar sesión en la base de conocimientos usando las credenciales de su aplicación cliente.

• Eliminar JWT: Haz clic en el botón Borrar para eliminar el JWT configurado. No puedes deshacer esta acción.

• Configuración básica de JWT: Pegar la URL de inicio de sesión obtenida de la aplicación del cliente.

  • Los lectores accederán a la página dedicada para los lectores de JWT SSO si no se proporciona un enlace personalizado para cerrar sesión.

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

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.

Lista de comprobación para desarrolladores

• Configura la URL de inicio de sesión, la URL de devolución de llamada y la URL de generación de código en la configuración de JWT.

• Genera y almacena de forma segura tu Secreto del Cliente (mostrado solo una vez).

• Configura la lógica backend para llamar a la URL de generación de código con autenticación básica.

• Valida y firma el JWT de forma segura en tu backend.

• Usa HTTPS para todos los endpoints.

• Comportamiento en la sesión de prueba, caducidad y renovación automática.

• Vigila errores 401 por códigos caducados o problemas con los 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.

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 ID del cliente.

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

Solució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.