Konfigurieren Sie JWT für das Knowledge Base-Widget

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.

Wie die JWT-Authentifizierung für das Widget funktioniert

JWT ist der empfohlene Ansatz, wenn die Sichtbarkeit Ihrer Wissensdatenbank auf Privat oder Gemischt eingestellt ist. In diesen Fällen müssen die Leser authentifiziert werden, bevor das Widget Inhalte anzeigen darf. JWT regelt das stillschweigend. Leser sehen nie einen separaten Anmeldebildschirm.

Verwenden Sie JWT für das Widget, wenn:

• Ihre Wissensdatenbank ist auf bestimmte Nutzer oder Lesergruppen beschränkt.
• Du möchtest Single Sign-on auf das Widget zugreifen, ohne eine separate Anmeldeaufforderung.
• Du musst kontrollieren, welche Inhalte jeder Leser basierend auf seiner Gruppenzugehörigkeit sieht.

Überblick über den Authentifizierungsfluss

Das obige 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.

Das obige Sequenzdiagramm zeigt den technischen Ablauf zwischen dem Browser des Nutzers, Ihrem Backend und dem Identitätsserver von Document360, um das JWT-Token zu erstellen und zu validieren.

Die folgenden Schritte erklären den vollständigen JWT-Authentifizierungsablauf:

1. Der Nutzer besucht Ihre Website, auf der das Document360-Widget eingebettet ist.
2. Das Widget sendet eine stille Anfrage an Ihren Authentifizierungsendpunkt (Token-Endpunkt), der in den Widget-Einstellungen konfiguriert ist.
3. Ihr Backend sendet eine Anfrage an Document360 mit den erforderlichen Zugangsdaten (Client-ID, Client Secret) und Leserdetails.
4. Document360 validiert die Anfrage und sendet ein unterschriebenes JWT an dein Backend zurück.
5. Dein Backend schickt das Token zurück an das Widget.
6. Das Widget verwendet dieses Token, um Artikel abzurufen und anzuzeigen, auf die der Leser Zugriff hat.
7. Wenn das Token abläuft, fordert das Widget automatisch ein neues Token an (sofern es so konfiguriert ist).

Bevor du anfängst

• Du musst eine Rolle als Projektverantwortlicher oder Administrator in Document360 haben.
• Mindestens ein Wissensdatenbank-Widget muss bereits existieren. Falls nicht, erstelle zuerst eine aus dem Connections > Knowledge Base-Widget. Mehr erfahren Sie unter Hinzufügen eines Widgets.
• Die Projektsichtbarkeit Ihrer Wissensbasis muss auf Privat oder Gemischt gesetzt sein. JWT ist für öffentliche Projekte nicht erforderlich.
• Du musst Zugriff auf deinen Backend-Server haben, um den Authentifizierungsendpunkt umzusetzen. Das Codebeispiel in diesem Artikel verwendet C#, aber dieselben Prinzipien gelten für jede serverseitige Sprache.
• Mindestens eine Lesergruppe muss in Ihrem Projekt konfiguriert sein. Das Widget benötigt mindestens eine gültige Lesergruppen-ID, um Inhalte darzustellen. Erfahren Sie mehr über JWT-Lesergruppen.

Schritt 1: Aktivieren und konfigurieren Sie JWT für das Widget

1. Navigiere zu Verbindungen () > Wissensdatenbank-Widget in der linken Navigationsleiste.

   Die Liste der Widgets erscheint.

2. Fahre mit der Maus über das Widget, das du konfigurieren möchtest, und klicke auf das Edit ()-Symbol.

3. Im Reiter Konfigurieren & Verbinden navigiere zum JWT-Akkordeon und schalte den Aktivieren-Schalter ein.

Die folgenden Felder werden angezeigt:

4. Klicken Sie auf Speichern , um die Änderungen anzuwenden.

Fügen Sie die autorisierte URL in Ihren Code ein und fügen Sie sie in den Skriptbereich Ihrer Webseite ein. Dies implementiert ein sicheres, authentifiziertes Widget, das unbefugten Zugriff von Drittanbietern verhindert.

Schritt 2: Implementierung des Authentifizierungs-Endpunkts

Nachdem Sie JWT im Portal konfiguriert haben, richten Sie einen Authentifizierungsendpunkt in Ihrer Backend-Anwendung ein. 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. Die gleiche Logik gilt für andere serverseitige Sprachen wie Node.js oder 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
        });
    }
}

Token-Validitätsregeln:

• Der Wert tokenValidity wird in Sekunden festgelegt. Das Minimum beträgt 300 Sekunden (5 Minuten) und das Maximum 86.400 Sekunden (1440 Minuten).
• Wenn Sie einen Wert außerhalb dieses Bereichs eingeben, passt das System ihn automatisch auf den nächstgelegenen gültigen Wert an. Zum Beispiel erhöht sich die Einstellung tokenValidity auf 60 Sekunden automatisch auf 300 Sekunden.
• Ein Wert von 900 Sekunden (15 Minuten) ist für die meisten Anwendungsfälle ein vernünftiger Standard. Kürzere Werte verbessern die Sicherheit, erhöhen aber die Backend-Last.

Schritt 3: Teste deine JWT-Widget-Konfiguration mit Postman

Nachdem du JWT im Portal eingerichtet und deinen Backend-Authentifizierungsendpunkt implementiert hast, verwende Postman, um zu bestätigen, dass deine Konfiguration wie erwartet funktioniert. Dieser Test überprüft, ob der Backend-Endpunkt Ihres Widgets ein gültiges JWT-Token zurückgibt.

1. Startpostbote.

2. Wählen Sie + Neuer Tab oder klicken Sie auf Neue > HTTP-Anfrage.

3. Stelle die Methode auf POST.

4. Im Feld der Anfrage-URL geben Sie die vollständige URL Ihres Backend-Endpunkts ein.

   Beispiel: https://yourdomain.com/authenticate

5. Gehe zum Reiter Autorisierung .

6. Unter Typ wähle Basis-Auth aus.

7. Geben Sie folgende Berechtigungen ein:

   • Benutzername: Deine Client-ID aus dem Document360-Portal.
   • Passwort: Dein Client Secret wurde generiert, als du das JWT erstellt hast.

8. Geh zum Body-Reiter .

9. Wähle RAW und wähle JSON aus dem Dropdown-Menü.

10. 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": 900,
  "widgetId": "your-widget-id",
  "projectId": "your-project-id"
}

Ersetze die Werte durch tatsächliche Daten aus deiner App und der Document360-Konfiguration.

11. Klicken Sie auf Senden.

Wenn die Anfrage erfolgreich ist, erhalten Sie eine Antwort wie folgt:

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

Überprüfen Sie Folgendes in der Antwort:

• Der Antwortstatus beträgt 200 OK.
• Der Antwortkörper enthält ein gültiges accessToken.
• Der Wert expiresIn entspricht deiner erwarteten Token-Gültigkeitsdauer in Sekunden.

Wenn alle drei korrekt sind, funktioniert deine JWT-Widget-Konfiguration wie vorgesehen.

Nächste Schritte

Nachdem deine JWT-Konfiguration überprüft und funktioniert hat, kannst du:

• Fügen Sie das Widget auf Ihre Website ein, indem Sie den Skript-Snippet in den Skriptbereich Ihrer Webseite einfügen.
• Verwalten Sie den Leserzugriff, indem Sie die Zuweisungen von Lesergruppen in Einstellungen > Benutzer & Berechtigungen > Leser & Gruppen aktualisieren. Erfahren Sie mehr unter Lesergruppen verwalten.
• Passe das Aussehen und Verhalten des Widgets im Reiter Anpassen im Widget-Editor an. Erfahren Sie mehr über die Anpassung des Widgets.

Best Practices

• Speichere das Client-Geheimnis in einem Secure Secrets Manager, nicht in Quellcode- oder Umgebungsdateien, die für die Versionskontrolle übertragen wurden.
• Stelle es so kurz ein, tokenValidity wie es dein Anwendungsfall zulässt. Eine kürzere Gültigkeit verringert das Expositionsfenster, wenn ein Token abgefangen wird.
• Teste immer mit Postman, bevor du live gehst, um Probleme mit Zugangsdaten oder Payload frühzeitig zu erkennen.
• Wenn Sie das Client-Secret wiederherstellen, aktualisieren Sie alle Widgets und Chatbots, die es teilen, bevor die Leser ihre nächste Sitzung beginnen. Das Geheimnis wird über alle JWT-fähigen Widgets und Chatbots im Projekt geteilt.
• Verwenden Sie Lesergruppen-IDs, um Inhaltsbeschränkungen auf Token-Ebene durchzusetzen, sodass Leser nur sehen, worauf sie Zugriff haben.

FAQ