JWT SSO opzetten

Wat is een JWT?

Een JSON Web Token (JWT) is een versleuteld tokenformaat dat gegevens, zoals authenticatie- en autorisatiegegevens, veilig tussen twee applicaties overdraagt. In Document360 wordt JWT gebruikt om lezersloggegevens te authenticeren.  Klik hier om meer te lezen over JWT.

Document360 gebruikt een benadering vergelijkbaar met PKCE (Proof Key for Code Exchange, een veilige OAuth-methode) om het JWT-token te genereren.

Enterprise SSO met JWT in Document360

Document360 ondersteunt JWT als een van zijn SSO (Single Sign-On) methoden voor het authenticeren van lezerslogins. Het biedt een veilige manier om authenticatie- en autorisatiegegevens over te dragen tussen uw applicatie en uw Document360 Knowledge base

Je kunt tot 5 JWT-configuraties per project maken. Tot 3 daarvan kunnen als inlogknoppen verschijnen op de inlogpagina met de lezer. Als je er meer dan 3 hebt, kunnen lezers nog steeds de resterende configuraties bereiken door hun domeinnaam in het domeinnaaminvoerveld op de inlogpagina in te voeren.

JWT werkt ook samen met SSO-providers zoals SAML en OpenID, je kunt ze allemaal tegelijk actief hebben in hetzelfde project.

De juiste SSO-methode kiezen: JWT vs SAML vs OpenID

Document360 ondersteunt drie SSO-opties voor lezerauthenticatie: JWT, SAML en OpenID Connect. De juiste methode kiezen hangt af van hoe je gebruikers beheert, welke infrastructuur je al hebt en hoeveel controle je nodig hebt over het inlogproces.

De onderstaande tabel vergelijkt JWT met de andere opties:

Hoe JWT werkt

Het onderstaande hoog-niveau diagram toont hoe je JWT in Document360 kunt bereiken.

De onderstaande stappen leggen de volledige JWT-authenticatieflow in Document360 uit voor ontwikkelaars die een reader SSO instellen met hun eigen inlogsysteem.

Belangrijke terminologie

Authenticatieflow

1. Gebruiker krijgt toegang tot de privé kennisbank

   • Wanneer een gebruiker probeert toegang te krijgen tot uw kennisbanksite, detecteert Document360 dat JWT SSO is ingeschakeld en verwijst de gebruiker naar de aanmeld-URL die in JWT-instellingen is geconfigureerd.

2. Gebruiker logt in bij je applicatie

   • Als de gebruiker nog niet geauthenticeerd is, verzorgt je inlogpagina hun authenticatie.

3. Je backend vraagt om een eenmalige authenticatiecode

   • Nadat de gebruiker is ingelogd, stuurt je backend een POST verzoek naar de codegeneratie-URL die in Document360 is geconfigureerd met het volgende:

     • Gebruikersidentiteit (bijv. naam, e-mail)

     • Optioneel readerGroupIds

     • tokenValidity Binnen enkele minuten

   • Dit verzoek moet worden geautoriseerd met HTTP Basic Auth met uw Client ID en Client Secret.

Voorbeeld autorisatieheader

Authorization: Basic Base64Encode(clientId:clientSecret)

JSON Payload voorbeeld

{
  "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
}

OPMERKING

Zorg voor correcte JSON-syntaxis om configuratiefouten te voorkomen.

4. De Document360 Identity-server geeft een authenticatiecode terug

   • Als het verzoek geldig is, genereert de identiteitsserver van Document360 een eenmalige autorisatiecode en stuurt deze terug naar je app (backend).

5. Je app stuurt de gebruiker terug naar Document360

   • Je backend voegt de code toe aan de Callback-URL en stuurt de gebruiker ernaartoe.

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

OPMERKING

De authenticatiecode is een eenmalige gebruikscode en kan niet opnieuw worden gebruikt.

6. Document360 valideert de code

   • Zodra de code is ontvangen, stuurt Document360 deze via backchannel naar de identiteitsserver om deze uit te wisselen voor een JWT-token.

7. Er wordt een lezersessie aangemaakt

   • Document360 haalt gebruikersinformatie en toegangsregels (gebaseerd op readerGroupIds) uit het token.

   • Er wordt een sessie voor de lezer aangemaakt, waardoor hij toegang krijgt tot toegestane categorieën, talen of versies.

Tokenvaliditeit en sessiegedrag

• Je kunt de sessieduur definiëren met het tokenValidity veld in de payload (min: 5 minuten, maximaal: 1440).

• Zodra de token verloopt:

  • De lezer wordt teruggeleid naar je aanmeld-URL.

  • Als de gebruiker nog steeds geauthenticeerd is in je app, wordt er een nieuwe code gegenereerd en wordt de sessie naadloos opnieuw ingesteld.

JWTconfigureren  in Document360

Configureer JSON Web Token (JWT)-authenticatie zodat lezers veilig kunnen inloggen met tokens van je applicatie of identiteitsprovider. Je kunt tot 5 JWT-configuraties per project aanmaken, met maximaal 3 als inlogknoppen weergegeven op de inlogpagina van de lezer voor snelle toegang. Extra JWT-opties blijven toegankelijk via het veld Domeinnaam. JWT werkt naadloos samen met SSO-providers zoals SAML en OpenID, waardoor meerdere authenticatiemethoden naast elkaar kunnen bestaan in hetzelfde project.

Om toegang te krijgen tot de JWT-pagina, ga naar Instellingen > Gebruikers & rechten > JWT.

Nieuw bij JWT op Document360

Als er geen JWT-configuratie in uw project bestaat, voltooi dan de volgende stappen in volgorde:

1. Configure JWT login — configureer gedeelde projectinstellingen op niveau.

2. Maak een JWT-configuratie — voeg je eerste JWT-configuratie toe.

3. Stel je applicatie in — koppel je applicatie aan Document360.

Extra JWT-configuraties en SSO-providers (SAML of OpenID) kunnen op elk moment aan hetzelfde project worden toegevoegd zonder dat bestaande configuraties worden beïnvloed.

Bestaande JWT-configuratie

Als je JWT vóór juni 2026 hebt ingesteld, verschijnt je bestaande configuratie in een alleen-lezen weergave. Je huidige JWT-configuratie blijft actief en lezers kunnen zich zonder onderbreking blijven aanmelden.
Wanneer je naar Instellingen > Gebruikers & Rechten > JWT gaat, kun je:

• Blijf de configuratie gebruiken: Geen wijzigingen nodig.

• Bewerk de configuratie: Klik op het Bewerken-icoon om de instellingen bij te werken.

• Verwijder de configuratie: Klik op het Verwijderen-icoon om het te verwijderen.

Voeg een andere JWT-configuratie toe

Klik op Create JWT om een nieuwe configuratie toe te voegen. Vervolgens configureer JWT-login en maak JWT-configuraties om extra JWT-configuraties te maken. Een project kan tot 5 JWT-configuraties hebben. Na het opslaan schakelt de pagina over naar de lijstweergave en toont alle geconfigureerde JWT-vermeldingen. Je bestaande configuratie blijft ongewijzigd

Configureer SSO naast JWT

Ga naar Instellingen > Gebruikers & Rechten > SSO-configuratie en stel je SSO-provider in. Je JWT-configuratie wordt helemaal niet beïnvloed. Beide zijn tegelijkertijd actief en lezers zullen beide opties op de inlogpagina zien. Zie JWT en SSO coëxistentie voor details over hoe de inlogpagina eruitziet.

Stap 1 — Configureer JWT-login

Klik op 'JWT inlogen configureren ' in de banner op de JWT-pagina om de configuratiemodus te openen.

Authenticatie

Dit zijn alleen-lezen waarden die door Document360 worden gegenereerd. Kopieer ze met de knop Kopiëren en configureer ze in je identiteitsprovider.

Andere instellingen

Direct JWT-login

Standaard: AAN

• Wanneer ingeschakeld, worden lezers direct doorgestuurd naar JWT-aanmelding zonder dat er een inlogselectiescherm wordt getoond. Dit is passend wanneer JWT de enige authenticatiemethode is voor je kennisbank.

• Wanneer uitgeschakeld, krijgen lezers een inlogselectiescherm te zien met alle geconfigureerde aanmeldopties — JWT, SSO en de standaard Document360-login. Schakel deze instelling uit wanneer meerdere authenticatiemethoden actief zijn en lezers hun aanmeldmethode moeten kiezen. Een bevestiging is vereist voordat deze wijziging wordt toegepast.

• Wanneer meerdere JWT-configuraties en SSO zijn ingesteld, maar de projecteigenaar wil dat lezers alleen via JWT-authenticatie inloggen, kunnen ze Direct JWT-login inschakelen.

Schakel de standaard inlogpagina uit

Standaard: UIT

• Wanneer ingeschakeld, is de standaard Document360 e-mail- en wachtwoordlogin verborgen. Lezers kunnen alleen authenticeren via geconfigureerde JWT- of SSO-providers. Dit wordt typisch gebruikt in bedrijfsomgevingen waar alle toegang tot lezers moet worden beheerd via een gecentraliseerd identiteitssysteem.

   OPMERKING

  Schakel deze instelling alleen in nadat JWT- of SSO-authenticatie volledig is geconfigureerd en getest. Als de externe authenticatieprovider verkeerd is geconfigureerd, kunnen lezers geen toegang krijgen tot de kennisbank.

Klik op Sluiten om de modal te verwijzen. Wijzigingen worden onmiddellijk doorgevoerd.

Stap 2 — Maak een JWT-configuratie aan

Klik op de JWT-pagina rechtsboven op 'JWT aanmaken '. De Create JWT-modal opent.

Naam

Voer een beschrijvende naam in om deze configuratie te identificeren - bijvoorbeeld Customer Portal SSO. Deze naam verschijnt in de JWT-lijst in het portaal. Als de inlogknop is ingeschakeld, wordt deze naam ook aan lezers op de inlogpagina weergegeven, dus het zou betekenisvol moeten zijn voor het publiek dat inlogt.

Authenticatie

Regels voor domeinnaamvalidatie:

• Subdomeinen worden behandeld als afzonderlijke elementen. portal.example.com en example.com zijn aparte domeinen en kunnen aan verschillende configuraties worden toegewezen.

• Wildcard-domeinen zoals deze *.example.com worden niet ondersteund. Elk domein moet een exacte waarde hebben.

• Een domein dat al aan een andere JWT-configuratie in hetzelfde project is toegewezen, kan niet opnieuw worden gebruikt. Een inline validatiefout wordt weergegeven bij het opslaan.

JWT-sleutels

BELANGRIJK

Geheime tokens worden slechts één keer getoond op het moment van creatie. Kopieer en bewaar ze veilig voordat je de modal sluit. Als ze verloren gaan, moeten ze worden geregenereerd, wat de vorige tokens onmiddellijk ongeldig maakt.

Document360 genereert automatisch twee geheime tokens wanneer de modal opent. Deze tokens zijn alleen in platte tekst zichtbaar tijdens deze sessie. Zodra de modal is gesloten, worden ze gemaskeerd en kunnen ze niet meer worden teruggehaald.

Gebruik het Kopieer-icoon naast elk token om de waarde te kopiëren.

Geavanceerde instellingen

Vouw de Geavanceerde instellingen uit om de volgende opties te configureren.

Schakel JWT-authenticatie in

Standaard: AAN

• Wanneer ingeschakeld, is deze configuratie actief en kunnen lezers deze gebruiken om in te loggen. Het uitschakelen deactiveert de configuratie zonder deze te verwijderen, wat handig is om een configuratie tijdelijk op te schorten zonder de instellingen te verliezen.

Toon inlogknop

Standaard: UIT

Wanneer ingeschakeld, verschijnt er een merk-loginknop voor deze configuratie op de kennisbank-inlogpagina. Dit biedt lezers een directe aanmeldoptie zonder dat ze een domeinnaam hoeven in te voeren.

 OPMERKING

Maximaal 3 JWT-inlogknoppen kunnen gelijktijdig op de inlogpagina worden weergegeven. Wanneer deze limiet is bereikt, wordt de toggle automatisch uitgeschakeld voor extra configuraties. Lezers die zijn toegewezen aan configuraties zonder zichtbare knop kunnen zich nog steeds authenticeren door hun domeinnaam in het domeinnaamveld op de inlogpagina in te voeren, wat hen naar de juiste configuratie stuurt.

Wanneer de knop Inlogknop Weergeven is ingeschakeld, zijn de volgende extra velden beschikbaar:

• Tekst van de inlogknop — het label dat op de knop wordt weergegeven. Dit zou duidelijk de authenticatiebron voor lezers moeten identificeren.

• Logo van de inlogknop — een afbeelding die is geüpload om de knop te merken. Geaccepteerde formaten: JPG, PNG, SVG Maximale bestandsgrootte: 512 KB.

Stap 3 — Stel je aanvraag in

Kopieer de volgende waarden uit de JWT-configuratie en voeg ze toe aan de bijbehorende velden in je clientapplicatie:

• Klant-ID

• Callback-URL

• Code generatie URL

• Primaire geheime token

• Secundair geheim token

Sla de configuratie op

Klik op Aanmaken. De knop blijft inactief totdat alle vereiste velden geldige waarden bevatten. Bij succes sluit de modal en verschijnt de nieuwe configuratie in de JWT-lijst.

 OPMERKING

Lezers hebben geen apart Document360-account nodig. Authenticatie wordt volledig via je applicatie afgehandeld. Een account in je applicatie is voldoende voor een lezer om toegang te krijgen tot de kennisbank

Ontwikkelaarschecklist

• Registreer de Login-URL, Callback-URL en Codegeneratie-URL in je JWT-instellingen.

• Bewaar het klantgeheim veilig. Het wordt slechts één keer getoond op het moment van creatie.

• Implementeer backendlogica om de Code generatie-URL aan te roepen met HTTP Basic Auth.

• Onderteken de JWT in je backend met je client secret. Stel nooit de signinglogica bloot aan de clientzijde.

• Handhaaf HTTPS op alle endpoints die betrokken zijn bij de authenticatieflow.

• Testsessiegedrag, tokenverloop en automatische sessieverlenging voordat het live gaat.

• Monitor backend-logs op 401-fouten, die doorgaans wijzen op verlopen autorisatiecodes of token-mismatches.

Implementatie van de JWT SSO-redirect-logica

Na het voltooien van de JWT-configuratie in Document360 heeft uw applicatie een backendroute nodig om de laatste stap van de inlogflow af te handelen.

Deze route:

• Valideert dat de gebruiker al geauthenticeerd is in je applicatie

• Stuurt een beveiligd verzoek naar de codegeneratie-URL van Document360

• Haalt een eenmalige autorisatiecode op

• Leidt de gebruiker door naar de kennisbanksite met die code

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

Je JWT-configuratie testen

Zodra je de JWT SSO-logica in je backend hebt geïmplementeerd, kun je de integratie testen met een van beide cURL of Postman. Deze tests simuleren hoe je backend communiceert met de Document360-identiteitsserver om een eenmalige autorisatiecode op te halen.

JWT-configuratie testen met 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
      }'

Na het inschakelen van de JWT-login kan de lezer via de clientapplicatie inloggen als lezersaccount op de kennisbanksite van Document360.

JWT-configuratie testen met Postman

Je kunt je JWT SSO-configuratie testen met Postman door handmatig een verzoek naar de Code generatie-URL te sturen. Dit stelt je in staat te verifiëren dat je clientgegevens en payload worden geaccepteerd en dat een eenmalige autorisatiecode succesvol is gegenereerd.

Om te testen met Postman, volg deze stappen:

1. Open Postman en maak een nieuw verzoek aan.

   Stel de aanvraagmethode in op POST, en voer in het URL-veld de Code generatie-URL in vanuit het JWT-configuratiescherm:

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

2. Ga naar het tabblad Autorisatie .

3. Stel het Type in op Basic Auth.

4. Voer in het veld Gebruikersnaam je Client ID in.

5. Voer in het veld Wachtwoord je Client Secret in.

6. Ga naar het tabblad Lichaam .

7. Selecteer de raw-optie en stel het formaat in op JSON.

8. Maak kennis met de vereiste JSON-payload. Voorbeeld:

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

9. Klik op Verzenden om het verzoek in te dienen.

Als de configuratie correct is, zou je een 200 OK eenmalige codereactie moeten ontvangen. Je kunt deze code vervolgens gebruiken om de lezer door te leiden naar de kennisbanksite en de SSO-inlogflow te voltooien.

Domeingebaseerde lezerroutering

Wanneer een lezer een domein invoert in het domeinnaamveld op de inlogpagina, vergelijkt Document360 dit met alle actieve JWT-configuraties en stuurt de lezer naar de bijbehorende inlog-URL van de bijbehorende configuratie.

Document360 hanteert een regel voor de meest-specifieke match. Als bijvoorbeeld zowel example.com als support.example.com zijn geconfigureerd, wordt een lezer die binnenkomt support.example.com naar de support.example.com configuratie gestuurd in plaats van naar het ouderdomein. Dit maakt het mogelijk om subdomeinen zonder conflicten door speciale configuraties te beheren.

Aanvullende routeringsregels:

• Domeinmatching is niet hoofdlettergevoelig en elke domeinnaam moet uniek zijn.

• Als de bijbehorende configuratie inactief is, wordt de lezer naar de standaard inlogopties gestuurd.

• Als er geen match wordt gevonden, wordt de lezer doorgestuurd naar de standaard inlogopties.

• Het domeinnaamveld is exclusief van toepassing op JWT-routering. SSO-providers zijn niet toegankelijk via dit veld.

JWT en SSO coëxistentie

JWT- en SSO (SAML- of OpenID)-configuraties kunnen gelijktijdig actief zijn in hetzelfde project. Elk type wordt onafhankelijk beheerd — het aanpassen van een JWT-configuratie heeft geen effect op de SSO-configuraties, en omgekeerd. Dit stelt organisaties in staat om lezers van verschillende identiteitssystemen te ondersteunen via één kennisbankportaal zonder conflicten tussen authenticatiemethoden.

Bijvoorbeeld, zakelijke klanten kunnen zich authenticeren via een JWT-gebaseerd systeem dat aan je applicatie is gekoppeld, terwijl interne teamleden zich aanmelden via een gecentraliseerde IdP zoals Okta met SAML. Beide methoden kunnen tegelijkertijd actief zijn zonder interferentie.

Limieten voor inlogknopen

Als bijvoorbeeld 5 JWT-configuraties actief zijn, verschijnen er 3 als inlogknoppen en zijn de resterende 2 alleen toegankelijk via domeininvoer. Als 6 SSO-configuraties actief zijn, zijn er slechts 5 toegankelijk — de 6e is niet bereikbaar voor lezers.

De JWT-limiet (3) en de SSO-limiet (5) worden onafhankelijk van elkaar toegepast. Het bereiken van de ene limiet heeft geen effect op de andere.

Wanneer de limiet van 3 knoppen voor JWT is bereikt, ontvangen alle projectbeheerders een systeemmelding: "Je hebt de limiet van 3 JWT-inlogknoppen bereikt. Extra JWT-configuraties verschijnen niet als knoppen op de inlogpagina. Lezers kunnen zich nog steeds aanmelden door hun domeinnaam in te voeren."

Op de inlogpagina van de lezer staat

De inlogpagina die aan lezers wordt getoond, wordt bepaald door twee factoren: de status van de schakelaar voor de standaard inlogpagina Uitschakelen , en welke JWT- en SSO-configuraties momenteel actief zijn.

Toepasselijke regels:

• Alleen actieve configuraties worden weergegeven. Inactieve configuraties worden nooit aan lezers getoond, ongeacht de toggle status.

• Het invoerveld voor domeinnaam wordt weergegeven wanneer de schakelaar AAN staat en minstens één JWT-configuratie actief is. Dit zorgt ervoor dat JWT-configuraties zonder zichtbare inlogknop bereikbaar blijven via domeininvoer.

• Als alle JWT- en SSO-configuraties inactief zijn terwijl de schakelaar AAN staat, krijgen lezers een bericht te zien dat er momenteel geen inlogopties beschikbaar zijn.

• Wijzigingen om de status of configuratiestatus te wisselen gaan direct in voor nieuwe lezersessies. Bestaande geauthenticeerde sessies worden niet beïnvloed.

Auditlogging en meldingen

Alle JWT-configuratieacties worden automatisch vastgelegd in het auditlogboek. Dit biedt een volledig en manipulatievrij overzicht van wijzigingen voor compliance- en beveiligingsbeoordelingsdoeleinden.

Gelogde acties:

• Aanmaken, Bijwerken, Verwijderen

• Inschakelen, uitschakelen

• Regenereer Primaire Token, Regenereer Secundaire Token

• Directe JWT-login inschakelen/uitschakelen

• Schakel de standaard inlogpagina in/uit

Elke logboekvermelding registreert het actietype, tijdstempel (UTC), de identiteit van de beheerder die de actie uitvoerde, en de configuratienaam op het moment van de actie. Voor updateacties bevat het logboek de specifieke velden die zijn veranderd, samen met de vorige en nieuwe waarden. Tokenwaarden worden nooit geregistreerd — alleen het feit van rotatie wordt geregistreerd om de beveiliging van de inloggegevens te beschermen.

Logs worden minimaal 90 dagen bewaard. Toegang tot JWT-auditlogboeken is beperkt tot gebruikers met Security & Audit-rechten.

Om JWT-activiteitstracking in Team Auditing in te schakelen, navigeer naar Instellingen > Beveiliging & Audit > Teamauditing > Auditconfiguratie en schakel de relevante JWT-gebeurtenisschakelaars in. Eenmaal ingeschakeld wordt JWT-activiteit geregistreerd in het tabblad Teamauditing . Gebruik het dropdown Event en zoek op "JWT" om records te filteren op eventtype.

Ontvangers van e-mailmeldingen:

Doorverwijzing naar andere pagina's in plaats van de startpagina

Standaard worden gebruikers na het inloggen doorgestuurd naar de startpagina van je kennisbank.

• Als je startpagina niet is gepubliceerd, worden gebruikers doorgestuurd naar de /docs-pagina .

• Om gebruikers door te leiden naar een andere pagina in je kennisbank (anders dan de Home - of /docs-pagina 's), configureer je de doorleiding tijdens de JWT-installatie met de volgende code.

URL-patroon

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

Parameters

• <Knowledge base URL>: De hoofd-URL van je knowledge base-site.

• <Code>: De code die wordt gegenereerd door het Document360-codegeneratie-eindpunt.

• <omleidingspad>: De nieuwe URL waar je wilt dat gebruikers landen na het inloggen.

Voorbeeld

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

OPMERKING

• Document360 zal de Redirectie-URL redirectPath naar het inlog-eindpunt sturen. Wanneer het inlog-eindpunt met de authenticatiecode terugstuurt naar de kennisbank, zou het de Redirectie-URL als parameter redirectUrl moeten teruggeven.

• In KB Site 2.0 wordt de omleiding afgehandeld met behulp van cookies in plaats van de redirectUrl parameter. Als je JWT-implementatie gebaseerd is op het omleiden van querystrings (met behulp van de redirectUrl parameter), houd dan rekening met dat de cookie-gebaseerde aanpak deze parameter niet ondersteunt. Je moet mogelijk je implementatie bijwerken of contact opnemen met de support voor verdere verduidelijking.

Probleemoplossing

Als je problemen ondervindt tijdens de JWT SSO-installatie, raadpleeg dan de volgende veelvoorkomende fouten en hun oplossingen:

401-ongeautoriseerde fout bij het testen van JWT in Postman

Fout: 401 Ongeautoriseerde fout

Als je een 401 Unauthorized fout tegenkomt tijdens het testen van JWT (JSON Web Token) met Postman, gebeurt dit meestal omdat de autorisatie-instellingen niet correct zijn geconfigureerd.

Stappen om op te lossen:

Om deze fout op te lossen,

1. Open in Postman het verzoek dat je aan het testen bent.

2. Ga naar het tabblad Autorisatie .

3. Stel het autorisatietype in op Basic Auth.

4. Voer in het veld Gebruikersnaam het Client-ID in.

5. Voer in het veld Wachtwoord het Client Secret in.

6. Ga naar het tabblad Lichaam .

7. Selecteer de raw-optie in het dropdown en zorg ervoor dat het formaat op JSON is ingesteld.

8. Voeg de benodigde JSON-payload toe voor het API-verzoek.

9. Klik op Verzenden om het verzoek uit te voeren.

Controleer de reactie voor de verwachte resultaten. Als het verzoek succesvol is, zou je een authenticatiecode of token in het antwoord moeten ontvangen.