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

Fonctionnement de l’authentification JWT pour le widget

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 pour le widget lorsque :

• Votre base de connaissances est limitée à des utilisateurs ou groupes de lecteurs spécifiques.
• Vous voulez un accès à la 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 du flux d’authentification

Le schéma de flux ci-dessus 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.

Le diagramme de séquence ci-dessus 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).

Avant que tu commences

• Vous devez avoir un rôle de Propriétaire de projet ou d’administrateur dans Document360.
• Au moins un widget de base de connaissances doit déjà exister. Sinon, créez-en un d’abord à partir du widget Connections > Knowledge base. Pour en savoir plus, consultez Ajouter un widget.
• La visibilité de votre projet de base de connaissances doit être réglée sur Privé ou Mixte. Le JWT n’est pas obligatoire pour les projets publics.
• Vous devez avoir 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 doit être configuré dans votre projet. Le widget nécessite au moins un identifiant de groupe de lecteurs valide pour afficher le contenu. En savoir plus sur les groupes de lecteurs JWT.

Étape 1 : Activer et configurer JWT pour le widget

1. Naviguez jusqu’à Connexions () > au widget de la base de connaissances dans la barre de navigation de gauche.

   La liste des widgets apparaît.

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

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

Les champs suivants sont affichés :

4. Cliquez sur Enregistrer pour appliquer les modifications.

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

Étape 2 : Implémenter le point d’accès d’authentification

Après avoir configuré JWT dans le portail, configurez 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.

/// <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}",
        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)
    {
        return StatusCode(500, new
        {
            message = "Failed to generate token.",
            details = ex.Message
        });
    }
}

Règles de validité des jetons :

• La tokenValidity valeur est fixée en secondes. Le minimum est de 300 secondes (5 minutes) et le maximum de 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, en réglant tokenValidity à 60 secondes, cela augmente automatiquement à 300 secondes.
• 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.

Étape 3 : Testez la configuration de vos widgets JWT avec Postman

Après avoir configuré JWT dans le portail et mis en place votre terminau d’authentification backend, utilisez Postman pour confirmer que votre configuration fonctionne comme prévu. Ce test vérifie que le point de terminaison backend de votre widget retourne un jeton JWT valide.

1. Lancez Postman.

2. Sélectionnez + Nouvel onglet ou cliquez sur Nouveau > 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. Va dans l’onglet Corps .

9. Sélectionnez le texte raw et choisissez JSON dans le menu déroulant.

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

11. Cliquez sur Envoyer.

Si la demande est acceptée, vous recevrez une réponse comme la suivante :

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

Vérifiez ce qui suit dans la réponse :

• Le statut de réponse est de 200 OK.
• Le corps de réponse contient un fichier valide accessToken.
• La expiresIn valeur correspond à la durée de validité attendue de votre jeton en quelques secondes.

Si les trois sont correctes, la configuration de votre widget JWT fonctionne comme prévu.

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 Paramètres > Utilisateurs & permissions > Lecteurs & groupes. En savoir plus sur la gestion des groupes de lecteurs.
• Personnalisez l’apparence et le comportement du widget depuis l’onglet Personnaliser de l’éditeur de widgets. En savoir plus sur la personnalisation du widget.

Meilleures pratiques

• Stockez le secret client dans un gestionnaire de secrets sécurisé, et non dans le code source ou les fichiers d’environnement engagés sous contrôle de version.
• Réglez tokenValidity aussi court que votre cas d’usage le permet. Une validité plus courte réduit la fenêtre d’exposition si un jeton est intercepté.
• Testez toujours avec Postman avant de lancer pour détecter les problèmes de crédibilité ou de charge utile en avance.
• Si vous régénérez le secret client, mettez à jour tous les widgets et chatbots qui le partagent avant que les lecteurs ne commencent leur prochaine session. Le secret est partagé entre tous les widgets et chatbots compatibles JWT du projet.
• Utilisez des identifiants de groupe de lecteurs pour faire respecter des restrictions de contenu au niveau du jeton afin que les lecteurs ne voient que ce à quoi ils sont autorisés à accéder.

FAQ