Konfigurieren Sie JWT für das Knowledge Base-Widget

Wenn Ihre Wissensdatenbank privat oder auf bestimmte Benutzer beschränkt ist, können Sie JWT (JSON Web Tokens) verwenden, um den Zugriff auf das eingebettete Document360-Widget sicher zu kontrollieren. Diese Einrichtung stellt sicher, dass nur authentifizierte Nutzer Artikel über das Widget ansehen können, ohne dass sie sich separat anmelden müssen.

Mit der JWT-Authentifizierung übernimmt Ihr System Login und Token-Generierung. Das Widget verwendet dieses Token dann, um Inhalte basierend auf der Zugriffsstufe 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 gesetzt ist. In diesen Fällen müssen die Leser authentifiziert werden, bevor das Widget Inhalte anzeigen darf. JWT behandelt dies 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 Knowledge Base-Widget muss bereits existieren. Falls nicht, erstelle zuerst eines aus Connections () > Knowledge Base-Widget. Mehr erfahren Sie unter Widget hinzufügen.
• Die Projektsichtbarkeit Ihrer Wissensbasis muss auf Privat oder Gemischt gesetzt sein. JWT ist für öffentliche Projekte nicht erforderlich.
• Sie müssen Zugriff auf Ihren Backend-Server haben, um den Authentifizierungsendpunkt zu implementieren. 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 in der linken Navigationsleiste zu Verbindungen () > Knowledge Base-Widget .

   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 Erweiterte Einstellungen 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 Dritter 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. Es verwendet die RequestTokenAsync Erweiterungsmethode aus der IdentityModel-Bibliothek. Die gleiche Logik gilt für andere serverseitige Sprachen wie Node.js oder 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
        });
    }
}

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 erhöhen die Sicherheit, erhöhen aber die Backend-Belastung.

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

Nachdem Sie JWT im Portal eingerichtet und Ihren Backend-Authentifizierungsendpunkt implementiert haben, verwenden Sie Postman, um zu bestätigen, dass Ihre 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.

Widget-Artikel auf der Wissensdatenbank öffnen

Wenn ein Leser im Widget auf das Symbol "Einen neuen Tab öffnen " klickt, öffnet sich der Artikel auf Ihrer Wissensdatenbank-Website. Das Widget und die Wissensdatenbank-Seite verwenden separate JWT-Sitzungen, sodass die Widget-Sitzung des Lesers sie nicht auf der Seite anmeldet.

Wenn Ihre Wissensdatenbank mehrere JWT-Konfigurationen hat, kann die Seite nicht bestimmen, welche JWT-Anmeldung der Leser verwenden soll, und der Leser sieht die allgemeine Anmeldeseite.

Um die Leser direkt zum Artikel zu führen, melden Sie sie von Ihrer eigenen Anwendung aus in die Wissensdatenbank ein und leiten Sie sie auf den Artikelpfad um. Für das URL-Format siehe Weiterleitung auf eine bestimmte Seite nach dem Login.

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 Verwaltung von Lesergruppen.
• Passen Sie das Aussehen und Verhalten des Widgets im Bildschirm Aussehen unter dem Tab Installation & Einrichtung 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.
• Setze tokenValidity so kurz, wie es dein Anwendungsfall erlaubt. Eine kürzere Gültigkeit verringert das Fenster der Exposition, 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-Geheimnis neu generieren, 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