Mise en place du JWT SSO

Qu'est-ce qu'un JWT ?

Un jeton web JSON (JWT) est un format de jeton chiffré qui transfère en toute sécurité des données, telles que les identifiants d'authentification et d'autorisation, entre deux applications. Dans Document360, JWT est utilisé pour authentifier les identifiants des lecteurs.  Cliquez ici pour lire à propos de JWT.

Document360 utilise une approche similaire à PKCE (Proof Key for Code Exchange, une méthode OAuth sécurisée) pour générer le jeton JWT.

SSO d'entreprise utilisant JWT dans Document360

Document360 prend en charge JWT comme l'une de ses méthodes SSO (Single Sign-On) pour authentifier les connexions des lecteurs. Il offre un moyen sécurisé de transférer les données d'authentification et d'autorisation entre votre application et votre Knowledge base Document360.

Vous pouvez créer jusqu'à 5 configurations JWT par projet. Jusqu'à 3 d'entre eux peuvent apparaître comme boutons de connexion sur la page de connexion destinée aux lecteurs. Si vous en avez plus de 3, les lecteurs peuvent toujours atteindre les configurations restantes en tapant leur nom de domaine dans le champ de saisie Nom de domaine sur la page de connexion.

JWT travaille aussi avec des fournisseurs SSO comme SAML et OpenID, vous pouvez tous les avoir actifs dans le même projet en même temps.

Choisir la bonne méthode SSO : JWT vs SAML vs OpenID

Document360 prend en charge trois options SSO pour l'authentification des lecteurs : JWT, SAML et OpenID Connect. Le choix de la bonne méthode dépend de la manière dont vous gérez les utilisateurs, de l'infrastructure que vous possédez déjà, et du contrôle nécessaire sur le processus de connexion.

Le tableau ci-dessous compare JWT aux autres options :

Fonctionnement de l'authentification JWT

Le diagramme de haut niveau ci-dessous montre comment obtenir un flux d'authentification JWT dans Document360.

Les étapes ci-dessous expliquent le flux complet d'authentification JWT dans Document360 pour les développeurs configurant le SSO du lecteur via leur propre système de connexion.

Terminologie clé

Flux d'authentification

1. L'utilisateur accède à la base de connaissances privée

   • Lorsqu'un utilisateur tente d'accéder à votre site de base de connaissances, Document360 détecte que JWT SSO est activé et redirige l'utilisateur vers l' URL de connexion configurée dans les paramètres JWT.

2. L'utilisateur se connecte à votre application

   • Si l'utilisateur n'est pas encore authentifié, votre page de connexion gère son authentification.

3. Votre backend demande un code d'authentification à usage unique

   • Après la connexion, votre backend envoie une POST requête à l' URL de génération de code configurée dans Document360 avec les éléments suivants :

     • Identité utilisateur (par exemple, nom, e-mail)

     • Optionnel readerGroupIds

     • tokenValidity en quelques minutes

   • Cette requête doit être autorisée en utilisant l'authentification HTTP Basic avec votre identifiant client et votre secret client.

Exemple d'en-tête d'autorisation

Authorization: Basic Base64Encode(clientId:clientSecret)

Exemple de charge utile 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
}

NOTE

Assurez-vous de tenir une syntaxe JSON correcte pour éviter les erreurs de configuration.

4. Le serveur Document360 Identity renvoie un code d'authentification

   • Si la requête est valide, le serveur d'identité de Document360 génère un code d'autorisation à usage unique et le renvoie à votre application (backend).

5. Votre application redirige l'utilisateur vers Document360

   • Votre backend ajoute le code à l' URL de rappel et y redirige l'utilisateur.

   • Par exemple : https://yourproject.document360.io/jwt/authorize?code=xyz

NOTE

Le code d'authentification est un code à usage unique et ne peut pas être réutilisé.

6. Document360 valide le code

   • Une fois le code reçu, Document360 l'envoie au serveur d'identité via un backchannel pour l'échanger contre un jeton JWT.

7. Session de lecture créée

   • Document360 extrait les informations utilisateur et les règles d'accès (basées sur readerGroupIds) du jeton.

   • Une session est créée pour le lecteur, lui donnant accès aux catégories, langues ou versions autorisées.

Validité du jeton et comportement de session

• Vous pouvez définir la durée de la session en utilisant le tokenValidity champ dans la charge utile (min : 5 minutes, max : 1440).

• Une fois le jeton expiré :

  • Le lecteur est redirigé vers votre URL de connexion.

  • Si l'utilisateur est toujours authentifié dans votre application, un nouveau code est généré, et la session est rétablie sans interruption.

Configuration JWT dans Document360

Configurez l'authentification JSON Web Token (JWT) pour permettre aux lecteurs de se connecter en toute sécurité à l'aide de jetons provenant de votre application ou fournisseur d'identité. Vous pouvez créer jusqu'à 5 configurations JWT par projet, avec jusqu'à 3 affichés comme boutons de connexion sur la page de connexion du lecteur pour un accès rapide. Des options JWT supplémentaires restent accessibles via le champ Nom de domaine. JWT fonctionne de manière transparente avec des fournisseurs SSO tels que SAML et OpenID, permettant la coexistence de plusieurs méthodes d'authentification dans un même projet.

Pour accéder à la page JWT, naviguez dans Paramètres > Utilisateurs et permissions > JWT.

Nouveau sur JWT sur Document360

Si aucune configuration JWT n'existe dans votre projet, suivez les étapes suivantes dans l'ordre :

1. Configurez la connexion JWT — configurez les paramètres partagés au niveau du projet.

2. Créez une configuration JWT — ajoutez votre première configuration JWT.

3. Configurez votre application — connectez-la à Document360.

Des configurations JWT supplémentaires et des fournisseurs SSO (SAML ou OpenID) peuvent être ajoutés au même projet à tout moment sans affecter les configurations existantes.

Configuration existante du JWT

Si vous configurez JWT avant juin 2026, votre configuration actuelle apparaît en vue en lecture seule. Votre configuration actuelle de JWT reste active, et les lecteurs peuvent continuer à se connecter sans interruption.
Lorsque vous naviguez dans Paramètres > Utilisateurs et Autorisations > JWT, vous pouvez :

• Continuez à utiliser la configuration : Aucun changement nécessaire.

• Modifier la configuration : Cliquez sur l' icône Modifier pour mettre à jour les paramètres.

• Supprime la configuration : Cliquez sur l' icône Supprimer pour la retirer.

Ajouter une autre configuration JWT

Cliquez sur Créer JWT pour ajouter une nouvelle configuration. Suivez, configurez la connexion JWT et créez la configuration JWT pour créer des configurations JWT supplémentaires. Un projet peut avoir jusqu'à 5 configurations JWT. Après l'enregistrement, la page passe à la vue liste et affiche toutes les entrées JWT configurées. Votre configuration actuelle reste inchangée

Configurez SSO avec JWT

Allez dans Paramètres > Utilisateurs et Permissions > Configuration SSO et configurez votre fournisseur SSO. Votre configuration JWT n'est pas du tout affectée. Les deux seront actifs en même temps et les lecteurs verront les deux options sur la page de connexion. Voir JWT et SSO coexistence pour plus de détails sur l'apparence de la page de connexion.

Étape 1 — Configurer la connexion JWT

Cliquez sur Configurer la connexion JWT dans la bannière sur la page JWT pour ouvrir le mode de configuration.

Authentification

Ce sont des valeurs en lecture seule générées par Document360. Copiez-les en utilisant le bouton Copier et configurez-les dans votre fournisseur d'identité.

Autres décors

Connexion directe JWT

Par défaut : ON

• Lorsqu'activé, les lecteurs sont redirigés directement vers la connexion JWT sans qu'un écran de sélection de connexion ne soit affiché. Cela est approprié lorsque JWT est la seule méthode d'authentification pour votre base de connaissances.

• Lorsqu'ils sont désactivés, les lecteurs voient un écran de sélection de connexion affichant toutes les options de connexion configurées — JWT, SSO et la connexion par défaut Document360. Désactivez ce paramètre lorsque plusieurs méthodes d'authentification sont actives et que les lecteurs doivent choisir leur méthode de connexion. Une confirmation est requise avant que ce changement ne soit appliqué.

• Lorsque plusieurs configurations JWT et SSO sont configurées, mais que le propriétaire du projet souhaite que les lecteurs se connectent uniquement via l'authentification JWT, ils peuvent activer la connexion JWT directe.

Désactiver la page de connexion par défaut

Par défaut : DÉSACTIVÉ

• Une fois activé, la connexion standard Document360 pour l'adresse email et le mot de passe sont masqués. Les lecteurs ne peuvent s'authentifier qu'auprès de fournisseurs JWT ou SSO configurés. Cela est généralement utilisé dans les environnements d'entreprise où tout l'accès des lecteurs doit être contrôlé via un système d'identité centralisé.

   NOTE

  Activez ce paramètre seulement après que l'authentification JWT ou SSO ait été entièrement configurée et testée. Si le fournisseur d'authentification externe est mal configuré, les lecteurs ne pourront pas accéder à la base de connaissances.

Cliquez sur Fermer pour supprimer le modal. Les changements sont appliqués immédiatement.

Étape 2 — Créer une configuration JWT

Sur la page JWT, cliquez sur Créer JWT en haut à droite. Le modal Create JWT s'ouvre.

Nom

Saisissez un nom descriptif pour identifier cette configuration – par exemple, Customer Portal SSO. Ce nom apparaît dans la liste JWT du portail. Si le bouton de connexion est activé, ce nom est également affiché aux lecteurs sur la page de connexion, il devrait donc avoir un sens pour le public qui se connecte.

Authentification

Règles de validation des noms de domaine :

• Les sous-domaines sont traités comme des entrées distinctes. portal.example.com et example.com sont des domaines distincts et peuvent être attribués à différentes configurations.

• Les domaines jokers tels que *.example.com ne sont pas pris en charge. Chaque domaine doit être une valeur exacte.

• Un domaine déjà assigné à une autre configuration JWT dans le même projet ne peut pas être réutilisé. Une erreur de validation en ligne est affichée lors de la sauvegarde.

Clés JWT

IMPORTANT

Les jetons secrets ne sont affichés qu'une seule fois au moment de la création. Copiez-les et stockez-les en toute sécurité avant de fermer le modal. S'ils sont perdus, ils doivent être régénérés, ce qui invalide immédiatement les jetons précédents.

Document360 génère automatiquement deux jetons secrets lorsque le modal s'ouvre. Ces jetons ne sont visibles en texte brut que pendant cette session. Une fois le modal fermé, ils sont masqués et ne peuvent plus être récupérés.

Utilisez l' icône Copier adjacente à chaque jeton pour en copier la valeur.

Paramètres avancés

Développez les paramètres avancés pour configurer les options suivantes.

Activer l'authentification JWT

Par défaut : ON

• Une fois activée, cette configuration est active et les lecteurs peuvent l'utiliser pour se connecter. La désactiver désactive la configuration sans la supprimer, ce qui est utile pour suspendre temporairement une configuration sans perdre ses paramètres.

Bouton Affichage de la connexion

Par défaut : DÉSACTIVÉ

Lorsqu'elle est activée, un bouton de connexion personnalisée pour cette configuration apparaît sur la page de connexion de la base de connaissances. Cela offre aux lecteurs une option de connexion directe sans avoir à saisir un nom de domaine.

 NOTE

Un maximum de 3 boutons de connexion JWT peuvent être affichés simultanément sur la page de connexion. Lorsque cette limite est atteinte, le bascule est automatiquement désactivé pour des configurations supplémentaires. Les lecteurs assignés à des configurations sans bouton visible peuvent toujours s'authentifier en saisissant leur nom de domaine dans le champ Nom de domaine sur la page de connexion, ce qui les oriente vers la bonne configuration.

Lorsque le bouton Afficher la connexion est activé, les champs supplémentaires suivants sont disponibles :

• Texte du bouton de connexion — l'inscription affichée sur le bouton Cela devrait clairement identifier la source d'authentification pour les lecteurs.

• Logo du bouton de connexion — une image téléchargée pour marquer le bouton. Formats acceptés : JPG, PNG, SVG Taille maximale du fichier : 512 Ko.

Étape 3 — Configurez votre application

Copiez les valeurs suivantes de la configuration JWT et ajoutez-les aux champs correspondants de votre application client :

• Client ID

• URL de rappel

• URL de génération de code

• Jeton secret principal

• Jeton secret secondaire

Sauvegarder la configuration

Cliquez sur Créer. Le bouton reste inactif jusqu'à ce que tous les champs requis contiennent des valeurs valides. En cas de succès, le modal se ferme et la nouvelle configuration apparaît dans la liste JWT.

 NOTE

Les lecteurs n'ont pas besoin d'un compte Document360 distinct. L'authentification est entièrement gérée via votre application. Un compte dans votre application suffit pour qu'un lecteur puisse accéder à la base de connaissances

Liste de contrôle des développeurs

• Enregistrez l'URL de connexion, l'URL de rappel et l'URL de génération de code dans vos paramètres JWT.

• Stockez le secret client de manière sécurisée. Il n'est exposé qu'une seule fois au moment de la création.

• Implémentez la logique backend pour appeler l'URL de génération de code en utilisant HTTP Basic Auth.

• Signez le JWT dans votre backend en utilisant votre secret client. Ne jamais exposer la logique de signes côté client.

• Imposez HTTPS à tous les points de terminaison impliqués dans le flux d'authentification.

• Comportement de session de test, expiration du jeton et renouvellement automatique de la session avant la mise en ligne.

• Surveillez les journaux backend pour détecter les erreurs 401, qui indiquent généralement des codes d'autorisation expirés ou des incompatibilités de jetons.

Implémentation de la logique de redirection SSO du JWT

Après avoir terminé la configuration JWT dans Document360, votre application a besoin d'une route backend pour gérer la dernière étape du flux de connexion.

Voici l'itinéraire :

• Valide que l'utilisateur est déjà authentifié dans votre application

• Envoie une requête sécurisée à l'URL de génération de code de Document360

• Récupère un code d'autorisation à usage unique

• Redirige l'utilisateur vers le site de la base de connaissances avec ce code

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

Test de votre configuration JWT

Une fois que vous avez implémenté la logique SSO JWT dans votre backend, vous pouvez tester l'intégration avec l'un ou cURL l'autre avec Postman. Ces tests simulent la façon dont votre backend communique avec le serveur d'identité Document360 pour récupérer un code d'autorisation à usage unique.

Test de la configuration JWT à l'aide de 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
      }'

Après avoir activé la connexion JWT, le lecteur peut utiliser l'application cliente pour se connecter en tant que compte lecteur sur le site de la base de connaissances Document360.

Test de la configuration JWT avec Postman

Vous pouvez tester votre configuration JWT SSO avec Postman en envoyant manuellement une requête à l'URL de génération de code. Cela vous permet de vérifier que vos identifiants et votre charge utile client sont acceptés et qu'un code d'autorisation à usage unique est généré avec succès.

Pour tester avec Postman, suivez ces étapes :

1. Ouvre Postman et crée une nouvelle demande.

   Réglez la méthode de requête sur POST, et dans le champ URL, entrez l'URL de génération de code depuis l'écran de configuration JWT :

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

2. Allez dans l'onglet Autorisation .

3. Définissez le Type à Basic Auth.

4. Dans le champ Nom d'utilisateur , saisissez votre identifiant client.

5. Dans le champ Mot de passe , saisissez votre Secret Client.

6. Naviguez jusqu'à l'onglet Corps .

7. Sélectionnez l'option raw et réglez le format sur JSON.

8. Voici la charge utile JSON requise. Exemple :

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

9. Cliquez sur Envoyer pour soumettre la demande.

Si la configuration est correcte, vous devriez recevoir une 200 OK réponse avec un fichier codeunique . Vous pouvez ensuite utiliser ce code pour rediriger le lecteur vers le site de la base de connaissances et compléter le flux de connexion SSO.

Routage de lecteur basé sur le domaine

Lorsqu'un lecteur saisit un domaine dans le champ Nom de domaine sur la page de connexion, Document360 le compare à toutes les configurations JWT actives et dirige le lecteur vers l'URL de connexion de la configuration correspondante.

Document360 applique une règle de correspondance très spécifique. Par exemple, si et sont configurésexample.com, un lecteur qui entre support.example.com est acheminé vers la support.example.com configuration plutôt que vers le domaine parent.support.example.com Cela permet de gérer les sous-domaines par des configurations dédiées sans conflit.

Règles de routage supplémentaires :

• La correspondance de domaine est insensible à la casse, et chaque nom de domaine doit être unique.

• Si la configuration correspondante est inactive, le lecteur est dirigé vers les options de connexion par défaut.

• Si aucune correspondance n'est trouvée, le lecteur est dirigé vers les options de connexion par défaut.

• Le champ Nom de domaine s'applique exclusivement au routage JWT. Les fournisseurs SSO ne peuvent pas être accessibles via ce domaine.

Coexistence entre JWT et SSO

Les configurations JWT et SSO (SAML ou OpenID) peuvent être actives simultanément dans un même projet. Chaque type est géré indépendamment — modifier une configuration JWT n'a aucun effet sur les configurations SSO, et inversement. Cela permet aux organisations de soutenir les lecteurs de différents systèmes d'identité via un portail de base de connaissances unique sans conflit entre les méthodes d'authentification.

Par exemple, les clients entreprise peuvent s'authentifier via un système basé sur JWT lié à votre application, tandis que les membres internes de l'équipe se connectent via un IDP centralisé comme Okta via SAML. Les deux méthodes peuvent être actives en même temps sans interférence.

Limites des boutons de connexion

Par exemple, si 5 configurations JWT sont actives, 3 apparaissent comme boutons de connexion et les 2 autres ne sont accessibles que via la saisie du domaine. Si 6 configurations SSO sont actives, seules 5 sont accessibles — la 6e ne peut être atteinte par les lecteurs.

La limite JWT (3) et la limite SSO (5) sont appliquées indépendamment. Atteindre une limite n'a aucun effet sur l'autre.

Lorsque la limite de 3 boutons pour JWT est atteinte, tous les administrateurs de projet reçoivent une notification système : « Vous avez atteint la limite de 3 boutons de connexion JWT. Les configurations JWT supplémentaires n'apparaîtront pas comme boutons sur la page de connexion. Les lecteurs peuvent toujours se connecter en saisissant leur nom de domaine. »

États de la page de connexion du lecteur

La page de connexion présentée aux lecteurs est déterminée par deux facteurs : l'état du bouton de désactivation de la page de connexion par défaut , et les configurations JWT et SSO actuellement actives.

Règles applicables :

• Seules les configurations actives sont affichées. Les configurations inactives ne sont jamais affichées aux lecteurs, quel que soit l'état du basculement.

• Le champ d'entrée Nom de domaine s'affiche chaque fois que le bascule est activé et qu'au moins une configuration JWT est active. Cela garantit que les configurations JWT sans bouton de connexion visible restent accessibles via la saisie de domaine.

• Si toutes les configurations JWT et SSO sont inactives alors que le basculement est activé, un message indique aux lecteurs qu'aucune option de connexion n'est actuellement disponible.

• Les modifications pour activer l'état ou l'état de configuration prennent effet immédiatement pour les nouvelles sessions de lecture. Les sessions authentifiées existantes ne sont pas affectées.

Journal et notifications d'audit

Toutes les actions de configuration JWT sont automatiquement capturées dans le journal d'audit. Cela fournit un dossier complet et inviolable des modifications pour des raisons de conformité et de contrôle de sécurité.

Actions enregistrées :

• Créer, mettre à jour, supprimer

• Activer, désactiver

• Régénérer le jeton principal, régénérer le jeton secondaire

• Activer/désactiver la connexion directe JWT

• Désactiver la page de connexion par défaut

Chaque entrée de journal enregistre le type d'action, l'horodatage (UTC), l'identité de l'administrateur qui a effectué l'action, ainsi que le nom de configuration au moment de l'action. Pour les actions de mise à jour, le journal capture les champs spécifiques qui ont changé ainsi que les valeurs précédentes et nouvelles. Les valeurs des jetons ne sont jamais enregistrées — seul le fait de la rotation est enregistré pour protéger la sécurité des identifiants.

Les journaux sont conservés pendant un minimum de 90 jours. L'accès aux journaux d'audit JWT est restreint aux utilisateurs disposant des autorisations Sécurité et Audit.

Pour permettre le suivi des activités JWT dans Team Auditing, allez dans Paramètres > Sécurité et Audit > Configuration d'audit > d'audit d'équipe et activez les basculements d'événements JWT pertinents. Une fois activée, l'activité JWT est enregistrée dans l'onglet d'audit de l'équipe . Utilisez le menu déroulant Événement et cherchez « JWT » pour filtrer les enregistrements par type d'événement.

Destinataires des notifications par email :

Redirection vers d'autres pages au lieu de la page d'accueil

Par défaut, après la connexion, les utilisateurs sont redirigés vers la page d'accueil de votre base de connaissances.

• Si votre page d'accueil n'est pas publiée, les utilisateurs seront redirigés vers la page /docs .

• Pour rediriger les utilisateurs vers une autre page de votre base de connaissances (autre que les pages Home ou /docs ), configurez la redirection lors de la configuration JWT en utilisant le code suivant.

Motif URL

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

Paramètres

• <URL de la base de connaissances > : L'URL principale de votre site de base de connaissances.

• <Code> : Le code généré par le point de terminaison de génération de code Document360.

• <chemin de redirection > : La nouvelle URL où vous souhaitez que les utilisateurs atterrissent après la connexion.

Exemple

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

NOTE

• Document360 enverra l' URL de Redirection vers redirectPath le point de terminaison de connexion. Lorsque le point de terminaison de connexion redirige vers la base de connaissances avec le code d'authentification, il doit retourner l' URL de redirection comme redirectUrl paramètre.

• Dans KB Site 2.0, la redirection est gérée via des cookies au lieu du redirectUrl paramètre. Si votre implémentation JWT est basée sur la redirection de chaînes de requête (en utilisant ce redirectUrl paramètre), veuillez noter que l'approche basée sur les cookies ne prend pas en charge ce paramètre. Vous devrez peut-être mettre à jour votre implémentation ou contacter le support pour plus de précisions.

Dépannage

Si vous rencontrez des problèmes lors de la configuration SSO JWT, référez-vous aux erreurs courantes suivantes et à leurs solutions :

Erreur 401 non autorisée lors du test de JWT dans Postman

Erreur : 401 Erreur non autorisée

Si vous rencontrez une erreur 401 non autorisée lors du test de JWT (JSON Web Token) via Postman, cela se produit généralement parce que les paramètres d'autorisation ne sont pas configurés correctement.

Étapes à résoudre :

Pour résoudre cette erreur,

1. Dans Postman, ouvrez la requête que vous testez.

2. Naviguez jusqu'à l'onglet Autorisation .

3. Réglez le type d'autorisation sur Authentification de base.

4. Dans le champ Nom d'utilisateur , saisissez l' ID du client.

5. Dans le champ Mot de passe , saisissez le Secret du client.

6. Va dans l'onglet Corps .

7. Sélectionnez l'option brute dans le menu déroulant et assurez-vous que le format est réglé sur JSON.

8. Ajoutez la charge utile JSON requise pour la requête API.

9. Cliquez sur Envoyer pour exécuter la demande.

Consultez la réponse pour connaître les résultats attendus. Si la requête est acceptée, vous devriez recevoir un code d'authentification ou un jeton dans la réponse.