Configuration de JWT pour le widget de la base de connaissances

Si votre base de connaissances est privée ou limitée à des utilisateurs spécifiques, vous pouvez utiliser JWT (JSON Web Tokens) pour contrôler en toute sécurité l’accès au widget Document360 intégré. Cette configuration garantit que seuls les utilisateurs authentifiés peuvent consulter les articles via le widget, sans avoir à se connecter séparément.

Avec l’authentification JWT, votre système gère la connexion et la génération de jetons. Le widget utilise ensuite ce jeton pour récupérer du contenu en fonction du niveau d’accès de chaque utilisateur.

Dans cet article, vous apprendrez :

• Comment fonctionne l’authentification JWT pour les widgets

• Comment configurer les paramètres JWT dans le portail Document360

• Comment configurer votre backend pour générer et retourner des jetons sécurisés

• Comment tester votre configuration JWT avec Postman

Comment fonctionne l’authentification JWT pour les widgets

JWT est l’approche recommandée lorsque la visibilité de votre base de connaissances est réglée sur Privé ou Mixte. Dans ces cas, les lecteurs doivent être authentifiés avant que le widget puisse afficher le contenu. JWT gère cela en silence — les lecteurs ne voient jamais d’écran de connexion séparé.

Utilisez JWT lorsque :

• Votre base de connaissances est limitée à des utilisateurs ou groupes de lecteurs spécifiques

• Vous voulez un accès à connexion unique au widget sans demande de connexion séparée

• Vous devez contrôler le contenu que chaque lecteur voit en fonction de son appartenance au groupe

Aperçu visuel du processus d’authentification

Ce diagramme de flux montre ce qui se passe lorsqu’un utilisateur charge un widget sur votre site web. Le widget Document360 communique avec votre système pour obtenir un jeton sécurisé avant d’afficher le contenu.

Diagramme de séquence du processus d’authentification

Ce diagramme de séquence décrit le flux technique entre le navigateur de l’utilisateur, votre backend et le serveur d’identité de Document360 pour générer et valider le jeton JWT.

Les étapes ci-dessous expliquent le flux complet d’authentification JWT :

1. L’utilisateur visite votre site web, où le widget Document360 est intégré.

2. Le widget envoie une requête silencieuse à votre point d’authentification (point de terminaison de jeton) configuré dans les paramètres du widget.

3. Votre backend envoie une requête à Document360 avec les identifiants requis (identifiant client, client secret) et les détails du lecteur.

4. Document360 valide la demande et renvoie un JWT signé à votre backend.

5. Votre backend renvoie le jeton au widget.

6. Le widget utilise ce jeton pour récupérer et afficher les articles auxquels le lecteur a accès.

7. Lorsque le jeton expire, le widget en demande automatiquement un nouveau (s’il est configuré pour cela).

NOTE
Le flux ci-dessus se déroule en coulisses. Les lecteurs ne voient jamais d’écran de connexion pour le widget.

Avant que tu commences

Avant de configurer JWT pour le widget, assurez-vous des éléments suivants :

• Vous avez un rôle de Propriétaire de Projet ou d’Administrateur dans Document360.

• Vous avez déjà créé au moins un widget de base de connaissances. Sinon, créez-en un d’abord à partir du widget Connections > Knowledge base.

• La visibilité de votre base de connaissances sur le projet est réglée sur Privé ou mixte. Le JWT n’est pas obligatoire pour les projets publics.

• Vous avez accès à votre serveur backend pour implémenter le point d’authentification. L’exemple de code de cet article utilise C#, mais les mêmes principes s’appliquent à tout langage côté serveur.

• Au moins un groupe de lecteurs est configuré dans votre projet. Le widget nécessite au moins un identifiant de groupe de lecteurs valide pour afficher le contenu.

Activez et configurez JWT pour le widget

Vous pouvez mettre en place une configuration d’authentification pour le widget via JWT, garantissant un environnement sécurisé pour les projets privés et mixtes.

1. Naviguer vers Connexions (⊞) > widget de la base de connaissances dans la barre de navigation de gauche.

   La liste des widgets apparaîtra.

2. Passez la souris sur le widget souhaité que vous souhaitez configurer et cliquez sur l’icône Modifier (✎).

3. Dans l’onglet Configurer & connecter, allez jusqu’à l’accordéon JWT et activez le bouton d’activation JWT.

1. Identification du client : L’identifiant client sera l’identifiant de votre projet.

2. ID du widget : Puisque plusieurs widgets peuvent exister, un ID de widget est fourni pour leurs usages spécifiques.

3. Extrémité du jeton : Un point d’accès de jeton est un point de terminaison HTTP qui vous permet d’obtenir un jeton d’accès à la suite d’un code d’autorisation.

4. Secret client : Cliquez sur Régénérer pour générer le secret client. Vous devez sauvegarder cela pour des usages futurs, et le même secret client s’appliquera à tous les widgets à l’avenir.

NOTE
Le secret client est partagé entre tous les widgets et chatbots compatibles JWT du projet. Si vous régénérez le secret, vous devez mettre à jour le nouveau secret dans tous les widgets et applications configurés par JWT pour éviter les échecs d’authentification.

Le secret client n’est affiché qu’à la génération et n’est pas stocké dans Document360, donc sauvegardez-le de manière sécurisée.

e. Autoriser l’URL : Collez l’URL autorisée depuis la page web du widget de votre base de connaissances.

4. Cliquez sur Enregistrer pour appliquer des modifications.

Intégrez l’URL autorisée dans votre code et collez-la dans la section script de votre page web. Cela mettra en place un widget sécurisé et authentifié qui empêchera l’accès non autorisé de tiers.

NOTE

Activer JWT supprime le jeton API du Widget Script. Si JWT est ensuite désactivé, un nouveau jeton API est automatiquement régénéré et restauré dans le Widget Script.

Implémentation du point d’arrivée de l’authentification

Après avoir configuré JWT dans le portail, vous devrez configurer un point d’authentification dans votre application backend. Ce point de terminaison reçoit une requête du widget et retourne un jeton valide en réponse.

L’exemple ci-dessous montre comment implémenter le point d’extrémité en C#. La même logique s’applique à d’autres langages côté serveur comme Node.js ou Python — adapter le client HTTP et les bibliothèques de sérialisation JSON selon les besoins.

/// <summary>
/// Endpoint to authenticate a user, generate a JWT token from Document360,
/// and return it to the widget.
/// </summary>
[HttpGet]
[Route("authenticate")]
public async Task<IActionResult> WidgetAuthentication(string id)
{
    // Ensure the user is authenticated in your application
    if (!HttpContext.User.Identity.IsAuthenticated)
    {
        return Unauthorized(new { message = "User is not authenticated." });
    }

    // Define configuration values
    var clientData = new ClientDetails
    {
        ClientId = "{Client ID}",                // Replace with your project's client ID
        Secret = "{Client secret}",              // Replace with your generated client secret
        TokenEndpoint = "{Token endpoint}",      // Replace with the token endpoint URL from Document360
        WidgetId = "{Widget ID}",                // Replace with your widget ID
        SecurityGroupIds = "group1,group2",      // Replace with comma-separated reader group IDs
        TokenValidity = 900                      // Token validity in seconds (300–86400)
    };

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

• La tokenValidity valeur est fixée en secondes. Il doit durer entre 300 secondes (5 minutes) et 86 400 secondes (1440 minutes). Si vous entrez une valeur en dehors de cette plage, le système l’ajuste automatiquement à la valeur valide la plus proche. Par exemple, si vous réglez tokenValidity à 60 secondes (1 minute), le système l’augmente à la valeur minimale autorisée de 300 secondes (5 minutes). Une valeur de 900 secondes (15 minutes) est un défaut raisonnable pour la plupart des cas d’utilisation — des valeurs plus courtes améliorent la sécurité mais augmentent la charge en arrière-plan.

• Le widget nécessite au moins un identifiant de groupe de lecteurs valide pour afficher le contenu. Incluez-les sous forme de liste séparée par virgules dans le readerGroupIds paramètre de la charge utile JWT.

Testez la configuration de votre widget JWT avec Postman

Après avoir configuré JWT dans le portail Document360 et mis en place votre point d’authentification backend, vous pouvez utiliser Postman pour confirmer que votre configuration fonctionne comme prévu.

Ce test simule ce que fait le widget : il envoie une requête à votre backend pour récupérer un JWT valide.

Installe le test dans Postman

1. Lancez Postman.

2. Sélectionnez + Nouvel onglet ou cliquez sur Nouvelle > requête HTTP.

3. Réglez la méthode sur POST.

4. Dans le champ URL de requête, saisissez l’URL complète de votre point de terminaison backend.

   Exemple : https://yourdomain.com/authenticate

5. Allez dans l’onglet Autorisation .

6. Dans Type, sélectionnez Authentification de base.

7. Saisissez les identifiants suivants :

   • Nom d’utilisateur : Votre identifiant client depuis le portail Document360.

   • Mot de passe : Votre secret client (généré lors de la création du JWT).

8. Ensuite, pour définir le corps de la demande, allez dans l’onglet Corps .

9. Sélectionne les crus.

10. Choisissez le JSON dans le menu déroulant à droite.

11. Collez l’exemple JSON suivant dans le corps :

    {
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "john.doe@example.com",
      "readerGroupIds": ["group1", "group2"],
      "tokenValidity": 900,
      "widgetId": "your-widget-id",
      "projectId": "your-project-id"
    }

    Remplacez les valeurs par des données réelles de votre application et de la configuration de Document360.

Si la requête est acceptée, vous recevrez une réponse JSON comme la suivante :

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900
}

• accessToken: C’est le JWT signé que le widget utilisera pour autoriser le lecteur.

• expiresIn: Validité du jeton en secondes (15 minutes = 900 secondes).

Après avoir envoyé la demande, vérifiez que le statut de la réponse est de 200 OK, indiquant une requête réussie. Le corps de la réponse doit contenir un , valide accessToken, qui est le JWT signé utilisé par le widget. De plus, confirmez que la expiresIn valeur correspond à la durée de validité attendue du jeton en secondes (par exemple, 900 secondes pendant 15 minutes).

Si toutes ces valeurs apparaissent correctement, votre configuration JWT fonctionne comme prévu.

Dépannage

Si la requête Postman ou le widget actif ne retourne pas un jeton valide, consultez les problèmes courants ci-dessous.

Prochaines étapes

Une fois votre configuration JWT vérifiée et fonctionnelle, vous pouvez :

• Intégrez le widget sur votre site web en ajoutant l’extrait de script dans la section script de votre page.

• Gérez l’accès des lecteurs en mettant à jour les affectations de groupes de lecteurs dans Connections > Readers.

• Personnalisez l’apparence et le comportement du widget depuis l’onglet Personnaliser de l’éditeur de widgets.