Konfiguration von 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.

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 teste du deine JWT-Konfiguration mit Postman

Wie die JWT-Authentifizierung für Widgets 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 still – die Leser sehen nie einen separaten Anmeldebildschirm.

JWT verwenden, wenn:

• Ihre Wissensdatenbank ist auf bestimmte Nutzer oder Lesergruppen beschränkt

• Du möchtest Single Sign-on auf das Widget ohne eine separate Anmeldeaufforderung

• Du musst kontrollieren, welche Inhalte jeder Leser basierend auf seiner Gruppenmitgliedschaft sieht

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:

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).

HINWEIS
Der oben genannte Ablauf findet hinter den Kulissen statt. Leser sehen nie einen Anmeldebildschirm für das Widget.

Bevor du anfängst

Bevor Sie JWT für das Widget konfigurieren, stellen Sie Folgendes sicher:

• Du hast eine Rolle als Projektleiter oder Administrator in Document360.

• Du hast mindestens ein Wissensdatenbank-Widget bereits erstellt. Falls nicht, erstelle zuerst eine über Connections > Knowledge Base-Widget.

• Die Projektsichtbarkeit Ihrer Wissensdatenbank ist auf Privat oder Gemischt gesetzt. JWT ist für öffentliche Projekte nicht erforderlich.

• Du hast Zugriff auf deinen Backend-Server, um den Authentifizierungsendpunkt zu implementieren. Das Codebeispiel in diesem Artikel verwendet C#, aber dieselben Prinzipien gelten für jede serverseitige Sprache.

• Mindestens eine Lesergruppe ist in Ihrem Projekt konfiguriert. Das Widget benötigt mindestens eine gültige Lesergruppen-ID, um Inhalte darzustellen.

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.

1. Navigieren Sie zu Verbindungen (⊞) > Knowledge Base-Widget in der linken Navigationsleiste.

   Die Liste der Widgets wird angezeigt.

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

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

1. Kunden-ID: Die Client-ID ist dann die ID Ihres Projekts.

2. Widget-ID: Da mehrere Widgets existieren können, wird eine Widget-ID für deren einzigartige Zwecke bereitgestellt.

3. Token-Endpunkt: Ein Token-Endpunkt ist ein HTTP-Endpunkt, der es ermöglicht, einen Zugriffstoken mit einem Autorisierungscode zu erhalten.

4. 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 über alle JWT-fähigen Widgets und Chatbots im Projekt geteilt. Wenn Sie das Geheimnis neu generieren, müssen Sie das neue Geheimnis in allen JWT-konfigurierten Widgets und Anwendungen aktualisieren, um Authentifizierungsfehler zu vermeiden.

Das Client-Geheimnis wird nur während der Generierung angezeigt und nicht in Document360 gespeichert, also speichern Sie es sicher.

e. URL autorisieren: Fügen Sie die autorisierte URL von Ihrer Wissensdatenbank-Widget-Webseite ein.

4. 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.

HINWEIS

Das Aktivieren von JWT entfernt das API-Token aus dem Widget-Skript. Wenn JWT anschließend deaktiviert wird, wird ein neues API-Token automatisch neu generiert und im Widget-Skript wiederhergestellt.

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. Die gleiche Logik gilt für andere serverseitige Sprachen wie Node.js oder Python – man passt die HTTP-Client- und JSON-Serialisierungsbibliotheken nach Bedarf an.

/// <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}",                     // 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
        });
    }
}

• Der Wert tokenValidity wird in Sekunden festgelegt. Es muss zwischen 300 Sekunden (5 Minuten) und 86.400 Sekunden (1440 Minuten) 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 60 Sekunden (1 Minute) setzttokenValidity, erhöht das System den Wert auf den minimalen erlaubten Wert von 300 Sekunden (5 Minuten). 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-Auslastung.

• Das Widget benötigt mindestens eine gültige Lesergruppen-ID, um Inhalte darzustellen. Fügen Sie diese als kommagetrennte Liste in den readerGroupIds Parameter 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

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-Geheimnis (generiert, als du das JWT erstellt hast).

8. Um den Request-Body festzulegen, gehe als Nächstes zum Body-Reiter .

9. Wähle roh aus.

10. Wählen Sie JSON im Dropdown-Menü rechts.

11. 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.

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.

Fehlerbehebung

Wenn die Postman-Anfrage oder das Live-Widget kein gültiges Token zurückgibt, siehe die häufigsten Probleme unten.

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 Lesergruppenzuweisungen in Connections > Readers aktualisieren.

• Passe das Aussehen und Verhalten des Widgets im Reiter Anpassen im Widget-Editor an.