Einrichtung von JWT SSO

Was ist ein JWT?

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

Enterprise SSO mit JWT in Document360

Document360 unterstützt JWT (JSON Web Token) als eine seiner SSO-Methoden (Single Sign-On), die hauptsächlich zur Authentifizierung von Leser-Logins verwendet wird. JWT bietet eine sichere Möglichkeit, Authentifizierungs- und Autorisierungsdaten zwischen Ihrer Anwendung und der Document360-Wissensdatenbank zu übertragen.

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

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:

JWT in Document360 konfigurieren

Bevor Sie JWT SSO implementieren, müssen Sie zuerst das JWT in Document360 konfigurieren und die erforderlichen Zugangsdaten erhalten.

Erstellung eines JWT

Um einen JSON Web Token (JWT) zu erstellen,

1. Melden Sie sich im Document360-Portal an.

2. Gehe zu ()> Benutzer & Berechtigungen > JWT.

3. Erstellen Sie hier ein JWT (Client Secret), indem Sie auf die Schaltfläche "JWT erstellen " klicken.

4. Kopiere das generierte Client-Geheimnis, indem du auf das Kopier-Symbol klickst und auf Schließen klickst.

HINWEIS

Das gleiche generierte Client-Geheimnis wird beim erneuten Besuch dieses Abschnitts nicht verfügbar sein. Falls erforderlich, muss das Geheimnis des Kunden regeneriert werden.

Die JWT-Konfigurationsseite mit allen Daten ist jetzt verfügbar.

Überblick über die JWT-Konfigurationsseite

Nachdem ein JWT erstellt wurde, ist die JWT-Konfigurationsseite sichtbar.

• Richten Sie Ihre Bewerbung ein: Kopiere die Client-ID, Callback-URL, Codegenerierungs-URL, Client-Geheimnis und füge sie in die entsprechenden Felder der Client-Anwendung ein

• JWT-Status: Schalten Sie den JWT SSO-Login für Leser mit diesem Schalter ein oder aus. Wenn der Schalter auf deaktiviert ist, können sich Leser nicht mit den Zugangsdaten ihrer Client-App auf der Knowledge Base-Seite anmelden.

• JWT löschen: Klicken Sie auf die Schaltfläche Löschen, um das konfigurierte JWT zu entfernen. Du kannst diese Handlung nicht rückgängig machen.

• JWT-Grundkonfiguration: Füge die Login-URL ein, die aus der Client-Anwendung stammt.

  • Leser landen auf der dedizierten Ausloggungsseite für JWT SSO-Leser, wenn kein benutzerdefinierter Anmeldelink bereitgestellt wird.

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

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.

Entwickler-Checkliste

• Konfigurieren Sie die Anmelde-URL, die Rückruf-URL und die Code-Generierungs-URL in den JWT-Einstellungen.

• Generiere und speichere dein Client-Geheimnis sicher (nur einmal gezeigt).

• Richte Backend-Logik so ein, dass sie die Codegenerierungs-URL mit Basic Auth aufruft.

• Validiere und unterschreibe die JWT sicher in deinem Backend.

• Nutze HTTPS für alle Endpunkte.

• Test-Sitzungsverhalten, Ablaufdatum und automatische Verlängerung.

• Überwachen Sie 401-Fehler aufgrund abgelaufener Codes oder Token-Probleme.

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.

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

• <Knowledge Base URL>: Die Haupt-URL Ihrer Knowledge Base-Website.

• <Code>: Die Client-ID.

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