Einrichtung von JWT SSO

Was ist ein JWT?

Ein JSON Web Token (JWT) ist ein verschlüsseltes Tokenformat, das Daten wie Authentifizierungs- und Autorisierungsdaten sicher zwischen zwei Anwendungen überträgt. In Document360 wird JWT zur Authentifizierung von Leser-Logins verwendet.  Klicken Sie hier, um mehr über JWT zu lesen.

Document360 verwendet einen ähnlichen Ansatz wie PKCE (Proof Key for Code Exchange, eine sichere OAuth-Methode), um das JWT-Token zu erzeugen.

Enterprise SSO mit JWT in Document360

Document360 unterstützt JWT als eine seiner SSO-Methoden (Single Sign-On) zur Authentifizierung von Leser-Logins. Es bietet eine sichere Möglichkeit, Authentifizierungs- und Autorisierungsdaten zwischen Ihrer Anwendung und Ihrer Document360-Wissensdatenbank zu übertragenKnowledge base.

Du kannst bis zu 5 JWT-Konfigurationen pro Projekt erstellen. Bis zu 3 davon können als Login-Buttons auf der leserweisenden Anmeldeseite erscheinen. Wenn Sie mehr als 3 haben, können Leser dennoch die restlichen Konfigurationen erreichen, indem sie ihren Domainnamen im Domainnamen-Eingabefeld auf der Anmeldeseite eingeben.

JWT arbeitet auch mit SSO-Anbietern wie SAML und OpenID zusammen, du kannst alle gleichzeitig im selben Projekt aktiv haben.

Wahl der richtigen SSO-Methode: JWT vs SAML vs OpenID

Document360 unterstützt drei SSO-Optionen zur Leserauthentifizierung: JWT, SAML und OpenID Connect. Die richtige Wahl hängt davon ab, wie Sie Benutzer verwalten, welche Infrastruktur Sie bereits haben und wie viel Kontrolle Sie über den Anmeldeprozess benötigen.

Die folgende Tabelle vergleicht JWT mit den anderen Optionen:

Wie JWT funktioniert

Das untenstehende High-Level-Diagramm zeigt, wie man den JWT in Document360 erreicht.

Die folgenden Schritte erklären den vollständigen JWT-Authentifizierungsablauf in Document360 für Entwickler, die Reader-SSO mit ihrem eigenen Login-System einrichten.

Schlüsselterminologie

Authentifizierungsablauf

1. Der Nutzer greift auf die private Wissensdatenbank zu.

   • Wenn ein Nutzer versucht, auf Ihre Wissensdatenbank zuzugreifen, erkennt Document360, dass JWT SSO aktiviert ist, und leitet den Benutzer auf die in den JWT-Einstellungen konfigurierte Anmelde-URL weiter.

2. Der Nutzer meldet sich in Ihrer Anwendung an

   • Wenn der Nutzer noch nicht authentifiziert ist, übernimmt deine Login-Seite die Authentifizierung.

3. Ihr Backend fordert einen einmaligen Authentifizierungscode an

   • Nachdem der Nutzer sich eingeloggt hat, sendet Ihr Backend eine POST Anfrage an die in Document360 konfigurierte Code-Generierungs-URL mit folgendem Inhalt:

     • Benutzeridentität (z. B. Name, E-Mail)

     • Optional readerGroupIds

     • tokenValidity In wenigen Minuten

   • Diese Anfrage muss über HTTP Basic Auth mit Ihrer Client-ID und Client Secret autorisiert werden.

Beispiel für Autorisierungsheader

Authorization: Basic Base64Encode(clientId:clientSecret)

Beispiel JSON-Nutzlasten

{
  "username": "firstname + lastname",
  "firstName": "firstname",
  "lastName": "lastname",
  "emailId": "user email",
  "readerGroupIds": ["Obtain from Reader groups overview page in the Document360 portal (Optional)"],
  "tokenValidity": 15 //minutes
}

HINWEIS

Stellen Sie eine korrekte JSON-Syntax sicher, um Konfigurationsfehler zu vermeiden.

4. Der Document360 Identity-Server liefert einen Authentifizierungscode zurück

   • Wenn die Anfrage gültig ist, generiert der Identitätsserver von Document360 einen Einmal-Autorisierungscode und sendet ihn zurück an Ihre App (Backend).

5. Deine App leitet den Nutzer zurück zu Document360 weiter

   • Dein Backend hängt den Code an die Callback-URL an und leitet den Nutzer dorthin weiter.

   • Zum Beispiel: https://yourproject.document360.io/jwt/authorize?code=xyz

HINWEIS

Der Authentifizierungscode ist ein einmaliger Verwendungscode und kann nicht wiederverwendet werden.

6. Document360 validiert den Code

   • Sobald er den Code erhält, sendet Document360 ihn per Backchannel an den Identitätsserver, um ihn gegen ein JWT-Token auszutauschen.

7. Eine Lesesitzung wird erstellt

   • Document360 extrahiert Benutzerinformationen und Zugriffsregeln (basierend auf readerGroupIds) aus dem Token.

   • Für den Leser wird eine Sitzung erstellt, die ihm Zugriff auf erlaubte Kategorien, Sprachen oder Versionen gewährt.

Tokenvalidität und Sitzungsverhalten

• Man kann die Sitzungsdauer anhand des Feldes tokenValidity im Payload definieren (mind: 5 Minuten, maximal: 1440).

• Sobald der Token abläuft:

  • Der Leser wird zurück zu Ihrer Anmelde-URL weitergeleitet.

  • Wenn der Nutzer in Ihrer App noch authentifiziert ist, wird ein neuer Code generiert und die Sitzung nahtlos wiederhergestellt.

JWT in Document360 konfigurieren

Konfigurieren Sie die JSON Web Token (JWT)-Authentifizierung, damit Leser sich sicher mit Token Ihrer Anwendung oder Ihrem Identitätsanbieter anmelden. Sie können bis zu 5 JWT-Konfigurationen pro Projekt erstellen, wobei bis zu 3 als Login-Buttons auf der Leser-Anmeldeseite angezeigt werden, um schnellen Zugriff zu ermöglichen. Zusätzliche JWT-Optionen bleiben über das Domainnamenfeld zugänglich. JWT arbeitet nahtlos mit SSO-Anbietern wie SAML und OpenID zusammen, sodass mehrere Authentifizierungsmethoden im selben Projekt koexistieren können.

Um auf die JWT-Seite zuzugreifen, gehen Sie zu Einstellungen > Benutzer & Berechtigungen > JWT.

Neu bei JWT auf Document360

Wenn in Ihrem Projekt keine JWT-Konfiguration vorhanden ist, führen Sie die folgenden Schritte in der Reihenfolge durch:

1. JWT-Login konfigurieren – Einstellungen auf gemeinsamer Projektebene konfigurieren.

2. Erstellen Sie eine JWT-Konfiguration – fügen Sie Ihre erste JWT-Konfiguration hinzu.

3. Richten Sie Ihre Anwendung ein – verbinden Sie Ihre Anwendung mit Document360.

Zusätzliche JWT-Konfigurationen und SSO-Anbieter (SAML oder OpenID) können jederzeit demselben Projekt hinzugefügt werden, ohne bestehende Konfigurationen zu beeinträchtigen.

Bestehende JWT-Konfiguration

Wenn du JWT vor Juni 2026 eingerichtet hast, erscheint deine bestehende Konfiguration in einer schreibgeschützten Ansicht. Ihre aktuelle JWT-Konfiguration bleibt aktiv, und die Leser können sich weiterhin ohne Unterbrechung anmelden.
Wenn Sie zu Einstellungen > Benutzer & Berechtigungen > JWT navigieren, können Sie:

• Verwenden Sie weiterhin die Konfiguration: Keine Änderungen erforderlich.

• Bearbeite die Konfiguration: Klicke auf das Bearbeitungssymbol , um die Einstellungen zu aktualisieren.

• Lösche die Konfiguration: Klicke auf das Löschen-Symbol , um sie zu entfernen.

Fügen Sie eine weitere JWT-Konfiguration hinzu

Klicken Sie auf JWT erstellen , um eine neue Konfiguration hinzuzufügen. Anschließend konfigurieren Sie JWT-Login und erstellen Sie JWT-Konfigurationen , um zusätzliche JWT-Konfigurationen zu erstellen. Ein Projekt kann bis zu 5 JWT-Konfigurationen haben. Nach dem Speichern wechselt die Seite zur Listenansicht und zeigt alle konfigurierten JWT-Einträge an. Deine bestehende Konfiguration bleibt unverändert

SSO neben JWT konfigurieren

Gehe zu Einstellungen > Benutzer & Berechtigungen > SSO-Konfiguration und richte deinen SSO-Anbieter ein. Deine JWT-Konfiguration ist überhaupt nicht betroffen. Beide sind gleichzeitig aktiv und die Leser sehen beide Optionen auf der Anmeldeseite. Siehe JWT- und SSO-Koexistenz für Details zum Aussehen der Login-Seite.

Schritt 1 — JWT-Login konfigurieren

Klicken Sie im Banner auf der JWT-Seite auf "JWT-Login konfigurieren ", um das Konfigurationsmodal zu öffnen.

Authentifizierung

Dies sind schreibgeschützte Werte, die von Document360 generiert werden. Kopieren Sie sie mit der Schaltfläche Kopieren und konfigurieren Sie sie in Ihrem Identitätsanbieter.

Weitere Schauplätze

Direkter JWT-Login

Standard: AN

• Wenn aktiviert, werden die Leser direkt zur JWT-Anmeldung weitergeleitet, ohne dass ein Anmeldebildschirm angezeigt wird. Das ist angemessen, wenn JWT die einzige Authentifizierungsmethode für Ihre Wissensdatenbank ist.

• Wenn deaktiviert, wird den Lesern ein Anmeldebildschirm angezeigt, der alle konfigurierten Anmeldeoptionen zeigt – JWT, SSO und das Standard-Document360-Login. Deaktivieren Sie diese Einstellung, wenn mehrere Authentifizierungsmethoden aktiv sind und die Leser ihre Anmeldemethode wählen müssen. Eine Bestätigung ist erforderlich, bevor diese Änderung angewendet wird.

• Wenn mehrere JWT-Konfigurationen und SSO eingerichtet sind, der Projektbesitzer aber möchte, dass die Leser sich nur über JWT-Authentifizierung anmelden, kann er die direkte JWT-Anmeldung aktivieren.

Deaktivieren Sie die Standard-Anmeldeseite

Standard: AUS

• Wenn aktiviert, sind die Standard-E-Mail- und Passwortanmeldungen von Document360 verborgen. Leser können sich nur über konfigurierte JWT- oder SSO-Anbieter authentifizieren. Dies wird typischerweise in Unternehmensumgebungen verwendet, in denen der gesamte Lesezugriff über ein zentralisiertes Identitätssystem gesteuert werden muss.

   HINWEIS

  Aktivieren Sie diese Einstellung erst, nachdem die JWT- oder SSO-Authentifizierung vollständig konfiguriert und getestet wurde. Wenn der externe Authentifizierungsanbieter falsch konfiguriert ist, können die Leser nicht auf die Wissensdatenbank zugreifen.

Klicken Sie auf Schließen, um das Modal zu schließen. Änderungen werden sofort umgesetzt.

Schritt 2 — Erstellen Sie eine JWT-Konfiguration

Auf der JWT-Seite klicken Sie oben rechts auf JWT erstellen . Das Create JWT-Modal öffnet sich.

Name

Geben Sie einen beschreibenden Namen ein, um diese Konfiguration zu identifizieren – zum Beispiel Customer Portal SSO. Dieser Name erscheint in der JWT-Liste im Portal. Wenn der Login-Button aktiviert ist, wird dieser Name auch den Lesern auf der Login-Seite angezeigt, sodass er für das Publikum, das sich anmeldet, bedeutungsvoll sein sollte.

Authentifizierung

Regeln zur Erkennung von Domainnamen:

• Unterdomänen werden als eigenständige Einträge behandelt. portal.example.com und example.com sind separate Domänen und können verschiedenen Konfigurationen zugewiesen werden.

• Wildcard-Domains wie diese *.example.com werden nicht unterstützt. Jede Domäne muss einen exakten Wert haben.

• Eine bereits einer anderen JWT-Konfiguration im selben Projekt zugewiesene Domain kann nicht wiederverwendet werden. Ein Inline-Validierungsfehler wird beim Speichern angezeigt.

JWT-Schlüssel

WICHTIG

Geheime Marken werden zum Zeitpunkt der Erstellung nur einmal angezeigt. Kopieren und bewahren Sie sie sicher auf, bevor Sie das Modal schließen. Wenn sie verloren gehen, müssen sie regeneriert werden, was die vorherigen Token sofort ungültig macht.

Document360 generiert automatisch zwei geheime Tokens, wenn das Modal geöffnet wird. Diese Token sind nur während dieser Sitzung im Klartext sichtbar. Sobald der Modal geschlossen ist, sind sie maskiert und können nicht mehr abgerufen werden.

Verwenden Sie das Kopieren-Symbol neben jedem Token, um dessen Wert zu kopieren.

Erweiterte Einstellungen

Erweiterte die Erweiterten Einstellungen , um die folgenden Optionen zu konfigurieren.

Aktivieren Sie die JWT-Authentifizierung

Standard: AN

• Wenn aktiviert, ist diese Konfiguration aktiv und Leser können sie zum Anmelden nutzen. Das Deaktivieren deaktiviert die Konfiguration, ohne sie zu löschen, was nützlich ist, um eine Konfiguration vorübergehend auszusetzen, ohne die Einstellungen zu verlieren.

Anmelde-Button anzeigen

Standard: AUS

Wenn aktiviert, erscheint auf der Login-Seite der Wissensdatenbank ein gebrandeter Login-Button für diese Konfiguration. Dies bietet den Lesern eine direkte Anmeldeoption, ohne einen Domainnamen eingeben zu müssen.

 HINWEIS

Auf der Anmeldeseite können maximal 3 JWT-Anmeldebuttons gleichzeitig angezeigt werden. Wenn dieses Limit erreicht ist, wird der Schalter automatisch für zusätzliche Konfigurationen deaktiviert. Leser, die Konfigurationen ohne sichtbaren Button zugewiesen sind, können sich weiterhin authentifizieren, indem sie ihren Domainnamen im Domainnamen-Feld auf der Anmeldeseite eingeben, wodurch sie zur richtigen Konfiguration weitergeleitet werden.

Wenn der Anmeldeknopf aktivieren aktiviert ist, stehen folgende zusätzliche Felder zur Verfügung:

• Login-Button-Text – das auf dem Button angezeigte Label Dies sollte die Authentifizierungsquelle für die Leser klar angeben.

• Login-Button-Logo – ein Bild, das hochgeladen wurde, um den Button zu branden. Akzeptierte Formate: JPG, PNG, SVG Maximale Dateigröße: 512 KB.

Schritt 3 – Richten Sie Ihre Bewerbung ein

Kopieren Sie die folgenden Werte aus der JWT-Konfiguration und fügen Sie sie den entsprechenden Feldern Ihrer Client-Anwendung hinzu:

• Kunden-ID

• Rückruf-URL

• Code-Generierungs-URL

• Primäres geheimes Token

• Sekundärer geheimer Token

Speichere die Konfiguration

Klicken Sie auf Erstellen. Der Button bleibt inaktiv, bis alle erforderlichen Felder gültige Werte enthalten. Nach Erfolg schließt sich das Modal und die neue Konfiguration erscheint in der JWT-Liste.

 HINWEIS

Leser benötigen kein separates Document360-Konto. Die Authentifizierung erfolgt vollständig über Ihre Anwendung. Ein Konto in Ihrer Anwendung reicht aus, damit ein Leser auf die Wissensdatenbank zugreifen kann

Entwickler-Checkliste

• Registrieren Sie die Login-URL, die Rückruf-URL und die Code-Generierungs-URL in Ihren JWT-Einstellungen.

• Bewahren Sie das Kundengeheimnis sicher auf. Sie wird zum Zeitpunkt der Entstehung nur einmal ausgestellt.

• Implementiere Backend-Logik, um die Codegenerierungs-URL mit HTTP Basic Auth aufzurufen.

• Unterschreibe das JWT in deinem Backend mit deinem Client Secret. Niemals die Signing-Logik auf der Client-Seite offenlegen.

• Setzen Sie HTTPS auf allen Endpunkten durch, die am Authentifizierungsfluss beteiligt sind.

• Testsitzungsverhalten, Token-Ablauf und automatische Sitzungsverlängerung vor dem Live-Gehen.

• Überwachen Sie Backend-Protokolle auf 401-Fehler, die typischerweise auf abgelaufene Autorisierungscodes oder Token-Missmatches hinweisen.

Implementierung der JWT SSO-Redirect-Logik

Nach Abschluss der JWT-Konfiguration in Document360 benötigt Ihre Anwendung eine Backend-Route, um den letzten Schritt des Login-Flows abzuwickeln.

Diese Route:

• Es wird überprüft, dass der Benutzer bereits in Ihrer Anwendung authentifiziert ist

• Sendet eine sichere Anfrage an die Code-Generierungs-URL von Document360

• Ruft einen einmaligen Autorisierungscode ab

• Leitet den Benutzer mit diesem Code auf die Wissensdatenbank-Seite um

     /// <summary>
     /// Example endpoint to authenticate a user and retrieve a token from the identity server,
     /// and redirect the user to the Knowledge Base (KB) using the token code.
     /// </summary>
     /// <param name="clientId">Client ID issued for your application</param>
     /// <param name="clientSecret">Client secret associated with the client ID</param>
     /// <returns>Redirects to the KB with the issued code</returns>
     [HttpGet]
     [Route("authenticate")]
     public async Task<IActionResult> AuthenticateAsync(string clientId, string clientSecret)
     {
         if (!HttpContext.User.Identity.IsAuthenticated)
         {
             // user is not authenticated, redirect to an error or login page
             return Unauthorized(new { message = "User not authenticated" });
         }

         // Ensure you have the correct client ID and secret from your Document360 JWT configuration
         var authToken = Encoding.ASCII.GetBytes($"{clientId}:{clientSecret}");

         // Create an HttpClient instance
         using var httpClient = new HttpClient();

         // Set the Authorization header with Basic authentication
         httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(authToken));

         // Prepare the payload with user information
         var payload = new
         {
             username = User.Identity.Name,
             firstName = "FirstName", // Replace or customize as needed
             lastName = "LastName",
             emailId = "user@example.com", // Replace with actual user email
             readerGroupIds = new List<string> { "group1", "group2" }, // Replace with actual reader group IDs if needed (Optional)
             tokenValidity = 3600 // Token validity in seconds (Optional, default is 5 minutes)
         };

         var payloadContent = new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");

         // Identity server token endpoint - replace with your actual URL
         string identityServerUrl = "codeGeneration endpoint, you can find that in JWT config portal";
         // KB login URL to redirect after successful token issuance
         string kbLoginUrl = "https://{your subdomain}.document360.io";

         var response = await httpClient.PostAsync(identityServerUrl, payloadContent);

         if (response.IsSuccessStatusCode)
         {
             var content = await response.Content.ReadAsStringAsync();
             var tokenJson = JObject.Parse(content);
             // Extract the code from the response
             var tokenCode = (string)tokenJson.SelectToken("code");

             // Construct the KB login URL with code query parameter
             string finalRedirectUrl = $"{kbLoginUrl}?code={tokenCode}";

             return Redirect(finalRedirectUrl);
         }
         else
         {
             // Handle error response from the identity server
             var error = await response.Content.ReadAsStringAsync();
             return StatusCode((int)response.StatusCode, new { error = "Token request failed", details = error });
         }
     }

const express = require('express');
const https = require('https');
const axios = require('axios');
const app = express();

// Middleware to parse JSON
app.use(express.json());

// Replace with your actual client ID and secret from Document360
const clientId = 'b20bf794-050c-4194-bc30-bd834c51adad';
const clientSecret = '07U7nXLbOY7-klsmWrOOT3_qHa631XMOuqSd_gl69I8';
const codeGenerationUrl = 'https://identity.document360.net/jwt/generateCode';
// Your D360 KB URL (Replace your-subdomain)
const kbLoginUrl = 'https://jwt-readergroup1-sep.document360.net/jwt/authorize';

// ROUTE: /authenticate
app.get('/authenticate', async (req, res) => {
  try {
    // Example — add your real auth logic
    const isAuthenticated = true;

    if (!isAuthenticated) {
      return res.status(401).json({ message: 'User not authenticated' });
    }

    // Basic Authorization header
    const authHeader = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

    // Payload to send to D360
    const payload = {
      username: 'john.doe',
      firstName: 'John',
      lastName: 'Doe',
      emailId: 'john.doe@example.com',
      readerGroupIds: ['group1', 'group2'],
      tokenValidity: 3600
    };

    // POST to D360 identity server to get the code
    const response = await axios.post(
      codeGenerateUrl,
      payload,
      {
        headers: {
          'Authorization': `Basic ${authHeader}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        httpsAgent: new https.Agent({ maxVersion: 'TLSv1.2' })
      }
    );

    const tokenCode = response.data?.code;

    if (!tokenCode) {
      return res.status(500).json({ message: 'No code received from Document360' });
    }

    console.log("Redirecting to:", `${kbLoginUrl}?code=${tokenCode}`);
    // Redirect user to KB with ?code=<token>
    return res.redirect(`${kbLoginUrl}?code=${tokenCode}`);

  } catch (error) {
    console.error("JWT SSO error:", error.message);

    return res.status(500).json({
      message: "JWT SSO failed",
      details: error.response?.data || error.message
    });
  }
});

import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

import java.nio.charset.StandardCharsets;
import java.util.*;

@RestController
public class JwtSsoController {

    private final String clientId = "your-client-id";
    private final String clientSecret = "your-client-secret";
    private final String codeGenerationUrl = "https://identity.document360.io/api/jwt/generate-code";
    private final String kbLoginUrl = "https://your-subdomain.document360.io/jwt/authorize";

    @GetMapping("/authenticate")
    public ResponseEntity<?> authenticate() {
        // Example: Check if user is authenticated in your system
        boolean isAuthenticated = true; // Replace with actual logic
        if (!isAuthenticated) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("User not authenticated");
        }

        // Create Basic Auth header
        String auth = clientId + ":" + clientSecret;
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes(StandardCharsets.UTF_8));
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Authorization", "Basic " + encodedAuth);
        headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

        // Construct payload
        Map<String, Object> payload = new HashMap<>();
        payload.put("username", "john.doe");
        payload.put("firstName", "John");
        payload.put("lastName", "Doe");
        payload.put("emailId", "john.doe@example.com");
        payload.put("readerGroupIds", Arrays.asList("group1", "group2"));
        payload.put("tokenValidity", 3600); // Optional

        HttpEntity<Map<String, Object>> request = new HttpEntity<>(payload, headers);
        RestTemplate restTemplate = new RestTemplate();

        try {
            ResponseEntity<Map> response = restTemplate.postForEntity(codeGenerationUrl, request, Map.class);

            if (response.getStatusCode() == HttpStatus.OK && response.getBody() != null) {
                String tokenCode = (String) response.getBody().get("code");

                if (tokenCode == null || tokenCode.isEmpty()) {
                    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                            .body("No code returned from Document360");
                }

                // Redirect to the KB site with code
                String redirectUrl = UriComponentsBuilder.fromHttpUrl(kbLoginUrl)
                        .queryParam("code", tokenCode)
                        .toUriString();

                HttpHeaders redirectHeaders = new HttpHeaders();
                redirectHeaders.setLocation(java.net.URI.create(redirectUrl));
                return new ResponseEntity<>(redirectHeaders, HttpStatus.FOUND); // 302 redirect

            } else {
                return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
                        .body("Failed to get code from Document360: " + response.getStatusCode());
            }

        } catch (Exception ex) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("JWT SSO error: " + ex.getMessage());
        }
    }
}

Teste deine JWT-Konfiguration

Sobald du die JWT-SSO-Logik im Backend implementiert hast, kannst du die Integration entweder mit Postman cURL oder Postman testen. Diese Tests simulieren, wie Ihr Backend mit dem Document360-Identitätsserver kommuniziert, um einen einmaligen Autorisierungscode abzurufen.

Testen der JWT-Konfiguration mit cURL

curl -X POST https://identity.document360.io/api/jwt/generate-code \
  -H "Authorization: Basic BASE64_ENCODED_CLIENTID:CLIENTSECRET" \
  -H "Content-Type: application/json" \
  --http2-prior-knowledge \
  --tls-max 1.2 \
  -d '{
        "username": "john.doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailId": "john.doe@example.com",
        "readerGroupIds": ["group1", "group2"],
        "tokenValidity": 15
      }'

Nach Aktivierung des JWT-Logins kann der Leser die Client-Anwendung nutzen, um sich als Reader-Konto auf der Knowledge-Base-Website Document360 anzumelden.

Tests der JWT-Konfiguration mit Postman

Sie können Ihre JWT-SSO-Konfiguration mit Postman testen, indem Sie eine Anfrage manuell an die Code-Generierungs-URL senden. So können Sie überprüfen, ob Ihre Client-Zugangsdaten und Ihre Nutzlast akzeptiert werden und dass ein einmaliger Autorisierungscode erfolgreich generiert wurde.

Um Postman zu testen, befolgen Sie diese Schritte:

1. Postman öffnen und eine neue Anfrage erstellen.

   Stellen Sie die Anfragemethode auf POST ein und geben Sie im URL-Feld die Codegenerierungs-URL aus dem JWT-Konfigurationsbildschirm ein:

   https://identity.document360.io/api/jwt/generate-code

2. Gehe zum Reiter Autorisierung .

3. Setze den Typ auf Basic Auth.

4. Im Feld Benutzername geben Sie Ihre Client-ID ein.

5. Im Passwortfeld geben Sie Ihr Client Secret ein.

6. Navigiere zum Reiter "Leichen".

7. Wählen Sie die RAW-Option und setzen Sie das Format auf JSON.

8. Hier kommt die erforderliche JSON-Nutzlast ins Spiel. Beispiel:

   {
     "username": "john.doe",
     "firstName": "John",
     "lastName": "Doe",
     "emailId": "john.doe@example.com",
     "readerGroupIds": ["group1", "group2"],
     "tokenValidity": 15
   }

9. Klicken Sie auf Senden , um die Anfrage einzureichen.

Wenn die Konfiguration korrekt ist, solltest du eine 200 OK Antwort mit einer einmaligen Antwort codeerhalten. Mit diesem Code können Sie den Leser dann zur Knowledge Base-Seite weiterleiten und den SSO-Login-Flow abschließen.

Domänenbasierte Leser-Routing

Wenn ein Leser eine Domain im Domainnamen-Feld auf der Anmeldeseite eingibt, vergleicht Document360 diese mit allen aktiven JWT-Konfigurationen und leitet den Leser zur Login-URL der entsprechenden Konfiguration weiter.

Document360 wendet eine Regel für die meist-spezifisch-Übereinstimmung an. Wenn zum Beispiel sowohl example.com als auch support.example.com konfiguriert sind, wird ein Reader, der eingeht support.example.com , an die support.example.com Konfiguration und nicht zur übergeordneten Domäne weitergeleitet. Dies ermöglicht es, Subdomänen von dedizierten Konfigurationen ohne Konflikte zu verwalten.

Zusätzliche Routing-Regeln:

• Domain-Matching ist nicht groß- und kleinschreibungsabhängig, und jeder Domainname muss einzigartig sein.

• Wenn die abgestimmte Konfiguration inaktiv ist, wird der Leser zu den Standard-Anmeldeoptionen geleitet.

• Wenn kein Treffer gefunden wird, wird der Leser auf die Standard-Anmeldeoptionen weitergeleitet.

• Das Domainname-Feld gilt ausschließlich für JWT-Routing. SSO-Anbieter sind über dieses Feld nicht zugänglich.

JWT und SSO koexistieren

JWT- und SSO-(SAML- oder OpenID)-Konfigurationen können gleichzeitig im selben Projekt aktiv sein. Jeder Typ wird unabhängig verwaltet – die Änderung einer JWT-Konfiguration hat keinen Einfluss auf die SSO-Konfigurationen und umgekehrt. Dies ermöglicht es Organisationen, Leser verschiedener Identitätssysteme über ein einziges Knowledge Base-Portal zu unterstützen, ohne Konflikte zwischen den Authentifizierungsmethoden.

Beispielsweise können sich Unternehmenskunden über ein JWT-basiertes System authentifizieren, das mit Ihrer Anwendung verknüpft ist, während interne Teammitglieder sich über einen zentralisierten IdP wie Okta mit SAML anmelden. Beide Methoden können gleichzeitig aktiv sein, ohne Störungen.

Einschränkungen der Login-Tasten

Wenn zum Beispiel 5 JWT-Konfigurationen aktiv sind, erscheinen 3 als Login-Buttons und die restlichen 2 sind nur über Domain-Eingabe zugänglich. Wenn 6 SSO-Konfigurationen aktiv sind, sind nur 5 zugänglich – die 6. kann von den Lesern nicht erreicht werden.

Das JWT-Limit (3) und das SSO-Limit (5) werden unabhängig voneinander angewendet. Das Erreichen eines Limits hat keine Auswirkungen auf das andere.

Wenn das 3-Tasten-Limit für JWT erreicht ist, erhalten alle Projektadministratoren eine Systembenachrichtigung: "Sie haben das Limit von 3 JWT-Login-Buttons erreicht. Zusätzliche JWT-Konfigurationen erscheinen nicht als Buttons auf der Anmeldeseite. Leser können sich weiterhin anmelden, indem sie ihren Domainnamen eingeben."

Angaben auf der Leser-Login-Seite

Die Anmeldeseite, die den Lesern angezeigt wird, wird durch zwei Faktoren bestimmt: den Zustand des Standard-Anmeldeseiten-Schalters deaktivieren und welche JWT- und SSO-Konfigurationen derzeit aktiv sind.

Geltende Regeln:

• Es werden nur aktive Konfigurationen angezeigt. Inaktive Konfigurationen werden den Lesern unabhängig vom Umschaltzustand nie angezeigt.

• Das Domain-Name-Eingabefeld wird angezeigt, wann immer der Schalter AN ist und mindestens eine JWT-Konfiguration aktiv ist. Dies stellt sicher, dass JWT-Konfigurationen ohne sichtbaren Anmeldeknopf über Domaineingabe erreichbar bleiben.

• Wenn alle JWT- und SSO-Konfigurationen inaktiv sind, während der Schalter AN ist, wird den Lesern eine Meldung angezeigt, dass derzeit keine Anmeldeoptionen verfügbar sind.

• Änderungen zum Umschalten von Zustand oder Konfigurationsstatus treten für neue Lesersitzungen sofort in Kraft. Bestehende authentifizierte Sitzungen sind nicht betroffen.

Audit-Logging und Benachrichtigungen

Alle JWT-Konfigurationsaktionen werden automatisch im Audit-Log erfasst. Dies bietet eine vollständige und manipulationssichere Aufzeichnung der Änderungen für Compliance- und Sicherheitsprüfungszwecke.

Protokollierte Aktionen:

• Erstellen, aktualisieren, löschen

• Aktivieren, deaktivieren

• Primäres Token regenerieren, sekundäres Token regenerieren

• Direkte JWT-Anmeldung aktivieren/deaktivieren

• Standard-Login-Seite aktivieren/deaktivieren

Jeder Logeintrag zeichnet den Aktionstyp, den Zeitstempel (UTC), die Identität des Administrators, der die Aktion ausgeführt hat, und den Konfigurationsnamen zum Zeitpunkt der Aktion auf. Für Aktualisierungsaktionen erfasst das Log die spezifischen geänderten Felder sowie die vorherigen und neuen Werte. Tokenwerte werden nie aufgezeichnet – nur die Tatsache der Rotation wird protokolliert, um die Sicherheit der Zugangsdaten zu schützen.

Logs werden mindestens 90 Tage aufbewahrt. Der Zugriff auf JWT-Auditprotokolle ist auf Benutzer mit Sicherheits- und Auditberechtigungen beschränkt.

Um die JWT-Aktivitätsverfolgung im Team-Audit zu aktivieren, navigieren Sie zu Einstellungen > Sicherheit & Audit > Team-Auditing > Audit-Konfiguration und aktivieren Sie die entsprechenden JWT-Ereignis-Schalter. Sobald aktiviert, wird die JWT-Aktivität im Team-Auditing-Tab aufgezeichnet. Verwenden Sie das Dropdown-Menü für Ereignisse und suchen Sie nach "JWT", um Datensätze nach Ereignistyp zu filtern.

Empfänger von E-Mail-Benachrichtigungen:

Weiterleitung auf andere Seiten statt auf die Startseite

Standardmäßig werden Nutzer nach dem Einloggen auf die Startseite Ihrer Wissensdatenbank weitergeleitet.

• Wenn deine Startseite unveröffentlicht ist, werden Nutzer auf die /docs-Seite weitergeleitet.

• Um Benutzer auf eine andere Seite in deiner Wissensdatenbank (außer der Startseite oder /docs-Seiten ) umzuleiten, konfiguriere die Weiterleitung während der JWT-Einrichtung mit folgendem Code.

URL-Muster

https://<Knowledge base URL>/jwt/authorize?code=<code>&redirectUrl=<redirect path>

Parameter

• <Wissensdatenbank-URL>: Die Haupt-URL Ihrer Wissensdatenbank-Website.

• <Code>: Der Code, der vom Document360-Codegenerierungsendpunkt generiert wird.

• <Umleitungspfad>: Die neue URL, auf die Nutzer nach dem Login landen sollen.

Beispiel

https://example.document360.io/jwt/authorize?code=FOTaS_SW6dLGytQXvrG_rRFGhyPvrDDrgxJAZzYvJcY&redirectUrl=/docs/5-basic-things-to-get-started

HINWEIS

• Document360 sendet die Weiterleitungs-URL an redirectPath den Login-Endpunkt. Wenn der Login-Endpunkt mit dem Authentifizierungscode zurück zur Wissensdatenbank umleitet, sollte er die Umleitungs-URL als Parameter redirectUrl zurückgeben.

• In KB Site 2.0 wird die Weiterleitung mithilfe von Cookies statt des Parameters redirectUrl durchgeführt. Wenn Ihre JWT-Implementierung auf der Umleitung von Abfragesträngen (unter Verwendung des Parameters) redirectUrl basiert, beachten Sie bitte, dass der cookie-basierte Ansatz diesen Parameter nicht unterstützt. Sie müssen möglicherweise Ihre Implementierung aktualisieren oder den Support kontaktieren , um weitere Klarstellungen zu erhalten.

Fehlerbehebung

Wenn Sie während der JWT-SSO-Einrichtung Probleme haben, beachten Sie die folgenden häufigen Fehler und deren Lösungen:

401-unautorisierter Fehler beim Testen von JWT in Postman

Fehler: 401 Unautorisierter Fehler

Wenn Sie beim Testen von JWT (JSON Web Token) mit Postman einen 401 Unautorisierten Fehler haben, passiert dies typischerweise, weil die Autorisierungseinstellungen nicht korrekt konfiguriert sind.

Schritte zur Lösung:

Um diesen Fehler zu beheben,

1. In Postman öffne die Anfrage, die du testest.

2. Navigiere zum Reiter Autorisierung .

3. Setze den Autorisierungstyp auf Basic Auth.

4. Im Feld Benutzername geben Sie die Client-ID ein.

5. Im Feld Passwort geben Sie das Client-Geheimnis ein.

6. Geh zum Body-Reiter .

7. Wählen Sie die RAW-Option im Dropdown-Menü und stellen Sie sicher, dass das Format auf JSON gesetzt ist.

8. Fügen Sie die erforderliche JSON-Nutzlast für die API-Anfrage hinzu.

9. Klicken Sie auf Senden , um die Anfrage auszuführen.

Überprüfe die Antwort auf die erwarteten Ergebnisse. Wenn die Anfrage erfolgreich ist, sollten Sie in der Antwort einen Authentifizierungscode oder ein Token erhalten.