Wenn Ihre Wissensdatenbank privat oder auf bestimmte Nutzer beschränkt ist, können Sie JWT (JSON Web Tokens) verwenden, um den Zugriff auf das eingebettete Document360-Widget sicher zu kontrollieren. Dieses Setup stellt sicher, dass nur authentifizierte Nutzer Artikel über das Widget einsehen können, ohne dass sie sich separat anmelden müssen.
Mit der JWT-Authentifizierung übernimmt Ihr System die Anmeldung und Token-Generierung. Das Widget nutzt dieses Token dann, um Inhalte basierend auf dem Zugriffslevel jedes Nutzers abzurufen.
In diesem Artikel erfahren Sie:
Wie JWT-Authentifizierung für Widgets funktioniert
Wie man JWT-Einstellungen im Document360-Portal konfiguriert
Wie man sein Backend so einrichtet, dass sichere Token generiert und zurückgegeben werden
Wie die JWT-Authentifizierung für Widgets funktioniert
Visueller Überblick über den Authentifizierungsprozess
Dieses Flussdiagramm zeigt, was passiert, wenn ein Nutzer ein Widget auf Ihrer Website lädt. Das Document360-Widget kommuniziert mit Ihrem System, um ein sicheres Token zu erhalten, bevor Inhalte angezeigt werden.
Sequenzdiagramm des Authentifizierungsprozesses
Dieses Sequenzdiagramm beschreibt den technischen Ablauf zwischen dem Browser des Nutzers, Ihrem Backend und dem Identitätsserver von Document360, um das JWT-Token zu erzeugen und zu validieren.
Die folgenden Schritte erklären den vollständigen JWT-Authentifizierungsablauf:
Der Nutzer besucht Ihre Website, auf der das Document360-Widget eingebettet ist.
Das Widget sendet eine stille Anfrage an Ihren Authentifizierungsendpunkt (Token-Endpunkt), der in den Widget-Einstellungen konfiguriert ist.
Ihr Backend sendet eine Anfrage an Document360 mit den erforderlichen Zugangsdaten (Client-ID, Client Secret) und Leserdetails.
Document360 validiert die Anfrage und sendet ein unterschriebenes JWT an dein Backend zurück.
Dein Backend schickt das Token zurück an das Widget.
Das Widget verwendet dieses Token, um Artikel abzurufen und anzuzeigen, auf die der Leser Zugriff hat.
Wenn das Token abläuft, fordert das Widget automatisch ein neues Token an (sofern es so konfiguriert ist).
HINWEIS
Der oben genannte Ablauf findet hinter den Kulissen statt. Leser sehen nie einen Anmeldebildschirm für das Widget.
Aktivieren und konfigurieren Sie JWT für das Widget
Sie können eine Authentifizierungskonfiguration für das Widget mit JWT implementieren, um eine sichere Umgebung für private und gemischte Projekte zu gewährleisten.
Navigiere zu Connections () > Knowledge Base-Widget in der linken Navigationsleiste.
Die Liste der Widgets wird angezeigt.
Fahre mit der Maus über das gewünschte Widget, das du konfigurieren möchtest, und klicke auf das Bearbeiten ()-Symbol.
Im Reiter Konfigurieren & Verbinden navigiere zum JWT-Akkordeon und aktiviere den Schalter JWT Enable ein.
Kunden-ID: Die Client-ID ist dann die ID Ihres Projekts.
Widget-ID: Da mehrere Widgets existieren können, wird eine Widget-ID für deren einzigartige Zwecke bereitgestellt.
Token-Endpunkt: Ein Token-Endpunkt ist ein HTTP-Endpunkt, der es ermöglicht, einen Zugriffstoken mit einem Autorisierungscode zu erhalten.
Kundengeheimnis: Klicken Sie auf Regenerieren , um das Client-Geheimnis zu generieren. Du musst das für zukünftige Zwecke speichern, und dasselbe Client-Geheimnis gilt in Zukunft für alle Widgets.
HINWEIS
Das Client-Geheimnis wird für JWT-Widgets, die du erstellen kannst, benötigt. Beachten Sie, dass diese Informationen nicht in Document360 gespeichert werden.
e. URL autorisieren: Fügen Sie die autorisierte URL von Ihrer Wissensdatenbank-Widget-Webseite ein.
Klicken Sie auf Speichern , um Änderungen anzuwenden.
Fügen Sie die autorisierte URL in Ihren Code ein und fügen Sie sie in den Skriptbereich Ihrer Webseite ein. Dies wird ein sicheres, authentifiziertes Widget implementieren, das unbefugten Zugriff von Drittanbietern verhindert.
Implementierung des Auth-Endpunkts
Nachdem Sie JWT im Portal konfiguriert haben, müssen Sie einen Authentifizierungsendpunkt in Ihrer Backend-Anwendung einrichten. Dieser Endpunkt erhält eine Anfrage vom Widget und gibt als Antwort ein gültiges Token zurück.
Das untenstehende Beispiel zeigt, wie man den Endpunkt in C# implementiert.
/// <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
});
}
}HINWEIS
Der Wert
tokenValiditywird in Minuten festgelegt. Es muss zwischen 5 Minuten (300 Sekunden) und 1440 Minuten (86.400 Sekunden) liegen. Wenn Sie einen Wert außerhalb dieses Bereichs eingeben, passt das System ihn automatisch auf den nächstgelegenen gültigen Wert an. Wenn man zum Beispiel auf 1 Minute (60 Sekunden) setzttokenValidity, erhöht das System den Wert auf den minimalen erlaubten Wert von 5 Minuten (300 Sekunden).Das Widget benötigt mindestens eine gültige Lesergruppen-ID, um Inhalte darzustellen. Fügen Sie diese als kommagetrennte Liste in den
readerGroupIdsParameter der JWT-Nutzlast ein.
Teste deine JWT-Widget-Konfiguration mit Postman
Nachdem Sie JWT im Document360-Portal eingerichtet und Ihr Backend-Authentifizierungs-Endpunkt implementiert haben, können Sie Postman verwenden, um zu bestätigen, dass Ihre Konfiguration wie erwartet funktioniert.
Dieser Test simuliert, was das Widget macht: Es sendet eine Anfrage an dein Backend, um ein gültiges JWT abzurufen.
Richte den Test in Postman ein
Startpostbote.
Wählen Sie + Neuer Tab oder klicken Sie auf Neue > HTTP-Anfrage.
Stelle die Methode auf POST.
Im Feld der Anfrage-URL geben Sie die vollständige URL Ihres Backend-Endpunkts ein.
Beispiel:
https://yourdomain.com/authenticateGehe zum Reiter Autorisierung .
Unter Typ wähle Basis-Auth aus.
Geben Sie folgende Berechtigungen ein:
Benutzername: Deine Client-ID aus dem Document360-Portal.
Passwort: Dein Client-Geheimnis (generiert, als du das JWT erstellt hast).
Um den Request-Body festzulegen, gehe als Nächstes zum Body-Reiter .
Wähle roh aus.
Wählen Sie JSON im Dropdown-Menü rechts.
Fügen Sie das folgende Beispiel-JSON in den Körper ein:
{ "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" }Ersetze die Werte durch tatsächliche Daten aus deiner App und der Document360-Konfiguration.
Wenn die Anfrage erfolgreich ist, erhalten Sie eine JSON-Antwort wie folgt:
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 900
}accessTokenDies ist das signierte JWT, das das Widget verwendet, um den Reader zu autorisieren.expiresIn: Token-Gültigkeit in Sekunden (15 Minuten = 900 Sekunden).
Nach dem Absenden der Anfrage wird überprüft, ob der Antwortstatus 200 OK beträgt, was auf eine erfolgreiche Anfrage hinweist. Der Antwortkörper sollte ein gültiges accessTokenenthalten , das vom Widget verwendete signierte JWT ist. Zusätzlich solltest du bestätigen, dass der expiresIn Wert der erwarteten Token-Gültigkeitsdauer in Sekunden entspricht (zum Beispiel 900 Sekunden für 15 Minuten).
Wenn alle diese Werte korrekt angezeigt werden, funktioniert dein JWT-Setup wie vorgesehen.