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ée 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 diagramme 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 d’abord un à partir de Connections () > widget de la base de connaissances. En savoir plus sur Ajouter un widget.
• La visibilité de votre base de connaissances doit être réglée sur Privé ou mixte. JWT n’est pas requis pour les projets publics.
• Vous devez avoir accès à votre serveur backend pour implémenter le point d’arrivée d’authentification. L’exemple de code dans 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 lecture valide pour afficher le contenu. En savoir plus sur les groupes de lecteurs JWT.

Étape 1 : Activer et configurer JWT pour le widget

1. Naviguer jusqu’à Connexions () > 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 Paramètres avancés , allez 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 reçoit une requête du widget et renvoie un jeton valide en réponse.

L’exemple ci-dessous montre comment implémenter le point d’extrémité en C#. Il utilise la méthode d’extension RequestTokenAsync de la bibliothèque IdentityModel. La même logique s’applique à d’autres langages côté serveur comme Node.js ou Python.

using IdentityModel.Client;

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

    // 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
    {
        // Create an HttpClient instance. In production, reuse a single instance
        // (for example, through IHttpClientFactory) instead of creating one per request.
        using var client = new HttpClient();

        // 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 l’augmente automatiquement à 300 secondes.
• Une valeur de 900 secondes (15 minutes) est un défaut raisonnable pour la plupart des cas d’usage. 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 implémenté votre point 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 renvoie 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.

Ouvrir des articles widget sur le site de la base de connaissances

Lorsqu’un lecteur clique sur l’icône Ouvrir dans un nouvel onglet dans le widget, l’article s’ouvre sur votre site de base de connaissances. Le widget et le site de la base de connaissances utilisent des sessions JWT séparées, donc la session widget du lecteur ne les connecte pas au site.

Si votre base de connaissances possède plusieurs configurations JWT, le site ne peut pas déterminer quelle connexion JWT le lecteur doit utiliser, et le lecteur voit la page de connexion générale.

Pour amener les lecteurs directement à l’article, connectez-les à la base de connaissances depuis votre propre application et redirigez-les vers le chemin de l’article. Pour le format URL, voir Rediriger vers une page spécifique après la connexion.

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 des 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 le panneau Apparence sous l’onglet Installation & Configuration dans 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