JWT SSO opzetten

Wat is een JWT?

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

Enterprise SSO met JWT in Document360

Document360 ondersteunt JWT (JSON Web Token) als een van zijn SSO (Single Sign-On) methoden, voornamelijk gebruikt voor het authenticeren van lezerslogins. JWT biedt een veilige manier om authenticatie- en autorisatiegegevens over te dragen tussen uw applicatie en de kennisbank van Document360.

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

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:

JWT configureren in Document360

Voordat je JWT SSO implementeert, moet je eerst de JWT configureren in Document360 en de benodigde inloggegevens verkrijgen.

Een JWT

Om een JSON Web Token (JWT) te maken,

1. Log in op het Document360-portaal.

2. Ga naar ()> Gebruikers & rechten > JWT.

3. Maak hier een JWT (Client secret) aan door op de knop JWT aanmaken te klikken.

4. Kopieer het gegenereerde cliëntgeheim door op het kopieer-icoon te klikken en op Sluiten te klikken.

OPMERKING

Hetzelfde gegenereerde klantgeheim zal niet beschikbaar zijn wanneer je deze sectie opnieuw bezoekt. Indien nodig moet het geheim van de cliënt worden geregenereerd.

De JWT-configuratiepagina met alle gegevens is nu beschikbaar.

Overzicht van de JWT-configuratiepagina

Nadat een JWT is aangemaakt, wordt de JWT-configuratiepagina zichtbaar.

• Stel je aanmelding op: Kopieer de Client ID, Callback URL, Code Generation URL, Client Secret en plak deze in de juiste velden in de clientapplicatie

• JWT-status: Zet de JWT SSO-login voor lezers aan of uit met deze schakelaar. Als de schakelaar op uitgeschakeld staat, kunnen lezers niet inloggen op de kennisbanksite met hun client-app-inloggegevens.

• JWT verwijderen: Klik op de Delete-knop om de geconfigureerde JWT te verwijderen. Je kunt deze handeling niet ongedaan maken.

• JWT basisconfiguratie: Plak de inlog-URL die uit de applicatie van de client is verkregen.

  • Lezers komen terecht op de speciale uitlogpagina voor JWT SSO-lezers als er geen aangepaste uitloglink wordt verstrekt.

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

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.

Ontwikkelaarschecklist

• Configureer de inlog-URL, callback-URL en codegeneratie-URL in de JWT-instellingen.

• Genereer en sla je Client Secret veilig op (slechts één keer getoond).

• Stel backendlogica in om de Code generatie-URL met Basic Auth aan te roepen.

• Valideer en onderteken de JWT veilig in je backend.

• Gebruik HTTPS voor alle eindpunten.

• Testsessiegedrag, vervaldatum en automatische verlenging.

• Houd 401-fouten in de gaten door verlopen codes of tokenproblemen.

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.

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 klant-ID.

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