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 fonctionne l’authentification JWT pour les widgets
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 :
L’utilisateur visite votre site web, où le widget Document360 est intégré.
Le widget envoie une requête silencieuse à votre point d’authentification (point de terminaison de jeton) configuré dans les paramètres du widget.
Votre backend envoie une requête à Document360 avec les identifiants requis (identifiant client, client secret) et les détails du lecteur.
Document360 valide la demande et renvoie un JWT signé à votre backend.
Votre backend renvoie le jeton au widget.
Le widget utilise ce jeton pour récupérer et afficher les articles auxquels le lecteur a accès.
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.
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.
Naviguer vers Connections () > widget de la base de connaissances dans la barre de navigation de gauche.
La liste des widgets apparaîtra.
Passez la souris sur le widget souhaité que vous souhaitez configurer et cliquez sur l’icône Modifier ().
Dans l’onglet Configurer & connecter, allez jusqu’à l’accordéon JWT et activez le bouton d’activation JWT.
Identification du client : L’identifiant client sera l’identifiant de votre projet.
ID du widget : Puisque plusieurs widgets peuvent exister, un ID de widget est fourni pour leurs usages spécifiques.
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.
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 sera nécessaire pour les widgets JWT que vous pouvez créer. Notez que ces informations ne seront pas stockées dans Document360.
e. Autoriser l’URL : Collez l’URL autorisée depuis la page web du widget de votre base de connaissances.
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.
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#.
/// <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 = 15 // Token validity in minutes (5–1440)
};
// 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
});
}
}NOTE
La
tokenValidityvaleur est fixée en minutes. Il doit durer entre 5 minutes (300 secondes) et 1440 minutes (86 400 secondes). 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égleztokenValidityà 1 minute (60 secondes), le système l’augmente à la valeur minimale autorisée de 5 minutes (300 secondes).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
readerGroupIdsparamè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
Lancez Postman.
Sélectionnez + Nouvel onglet ou cliquez sur Nouveau > requête HTTP.
Réglez la méthode sur POST.
Dans le champ URL de requête, saisissez l’URL complète de votre point de terminaison backend.
Exemple :
https://yourdomain.com/authenticateAllez dans l’onglet Autorisation .
Dans Type, sélectionnez Authentification de base.
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).
Ensuite, pour définir le corps de la demande, allez dans l’onglet Corps .
Sélectionne les crus.
Choisissez le JSON dans le menu déroulant à droite.
Collez l’exemple JSON suivant dans le corps :
{ "username": "john.doe", "firstName": "John", "lastName": "Doe", "emailId": "john.doe@example.com", "readerGroupIds": ["group1", "group2"], "tokenValidity": 15, "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.