JWT configureren voor de kennisbankwidget

Als je kennisbank privé is of beperkt tot specifieke gebruikers, kun je JWT (JSON Web Tokens) gebruiken om veilig de toegang tot de ingebedde Document360-widget te controleren. Deze opzet zorgt ervoor dat alleen geauthenticeerde gebruikers artikelen via de widget kunnen bekijken, zonder dat ze apart hoeven in te loggen.

Met JWT-authenticatie verzorgt je systeem het inloggen en tokengenereren. De widget gebruikt dat token vervolgens om content op te halen op basis van het toegangsniveau van elke gebruiker.

In dit artikel leer je:

• Hoe JWT-authenticatie werkt voor widgets

• Hoe je JWT-instellingen configureert in het Document360-portaal

• Hoe je je backend instelt om veilige tokens te genereren en terug te sturen

• Hoe test je je JWT-configuratie met Postman

Hoe JWT-authenticatie voor widgets werkt

JWT is de aanbevolen aanpak wanneer de zichtbaarheid van je kennisbasis op Privé of Gemengd staat. In deze gevallen moeten lezers worden geauthenticeerd voordat de widget inhoud kan weergeven. JWT regelt dit stilletjes — lezers zien nooit een apart inlogscherm.

Gebruik JWT wanneer:

• Je kennisbank is beperkt tot specifieke gebruikers of lezersgroepen

• Je wilt single sign-on toegang tot de widget zonder een aparte inlogprompt

• Je moet bepalen welke inhoud elke lezer ziet op basis van hun groepslidmaatschap

Visueel overzicht van het authenticatieproces

Dit stroomdiagram laat zien wat er gebeurt wanneer een gebruiker een widget op je website laadt. De Document360-widget communiceert met je systeem om een beveiligd token te krijgen voordat de inhoud wordt weergegeven.

Sequentiediagram van het authenticatieproces

Dit sequentiediagram schetst de technische flow tussen de browser van de gebruiker, je backend en de identiteitsserver van Document360 om het JWT-token te genereren en te valideren.

De onderstaande stappen leggen de volledige JWT-authenticatieflow uit:

1. De gebruiker bezoekt je website, waar de Document360-widget is ingebed.

2. De widget stuurt een stille aanvraag naar je authenticatie-endpoint (token-endpoint) dat in de widget-instellingen is geconfigureerd.

3. Je backend stuurt een verzoek naar Document360 met de vereiste gegevens (client ID, client secret) en lezersgegevens.

4. Document360 valideert het verzoek en stuurt een ondertekende JWT terug naar je backend.

5. Je backend stuurt de token terug naar de widget.

6. De widget gebruikt dit token om artikelen op te halen en weer te geven waar de lezer toegang toe heeft.

7. Wanneer het token verloopt, vraagt de widget automatisch een nieuwe aan (indien geconfigureerd).

OPMERKING
De bovenstaande flow vindt achter de schermen plaats. Lezers zien nooit een inlogscherm voor de widget.

Voordat je begint

Voordat je JWT voor de widget configureert, zorg ervoor dat het volgende volgt:

• Je hebt een rol als Project Owner of Admin in Document360.

• Je hebt al minstens één kennisbasis-widget gemaakt. Zo niet, maak er dan eerst een aan via de widget Connections > Knowledge Base.

• De zichtbaarheid van je kennisbasisproject, staat op Privé of Gemengd. JWT is niet vereist voor openbare projecten.

• Je hebt toegang tot je backendserver om het authenticatie-endpoint te implementeren. Het codevoorbeeld in dit artikel gebruikt C#, maar dezelfde principes gelden voor elke server-side taal.

• Er is minstens één lezersgroep geconfigureerd in je project. De widget vereist ten minste één geldige lezersgroep-ID om de inhoud weer te geven.

Schakel JWT in en configureer JWT voor de widget

Je kunt een authenticatieconfiguratie voor de widget implementeren met JWT, wat zorgt voor een veilige omgeving voor privé- en gemengde projecten.

1. Navigeer naar Connections (⊞) > Knowledge Base-widget in de linker navigatiebalk.

   De lijst met widgets zal verschijnen.

2. Beweeg je muis over de gewenste widget die je wilt configureren en klik op het pictogram Bewerken (✎) ().

3. Ga in het tabblad Configureren & verbinden naar de JWT-accordeon en zet de JWT Enable schakelaar aan.

1. Klant-ID: De client ID is de ID van je project.

2. Widget-ID: Omdat meerdere widgets kunnen bestaan, wordt een widget-ID verstrekt voor hun unieke doeleinden.

3. Token-eindpunt: Een token-eindpunt is een HTTP-eindpunt waarmee je een toegangstoken kunt verkrijgen op basis van een autorisatiecode.

4. Klantgeheim: Klik op Regenereren om het cliëntgeheim te genereren. Je moet dit opslaan voor toekomstige doeleinden, en hetzelfde clientgeheim geldt in de toekomst voor alle widgets.

OPMERKING
Het client secret wordt gedeeld over alle JWT-geschikte widgets en chatbots in het project. Als je het geheim opnieuw genereert, moet je het nieuwe geheim bijwerken in alle JWT-geconfigureerde widgets en applicaties om authenticatiefouten te voorkomen.

Het clientgeheim wordt alleen getoond tijdens het genereren en is niet opgeslagen in Document360, dus sla het veilig op.

e. URL autoriseren: Plak de geautoriseerde URL van de widget-webpagina van je kennisbank.

4. Klik op Opslaan om wijzigingen toe te passen.

Embed de geautoriseerde URL in je code en plak deze in het scriptgedeelte op je webpagina. Dit zal een veilige, geauthenticeerde widget implementeren die ongeautoriseerde toegang van derden voorkomt.

OPMERKING

Het inschakelen van JWT verwijdert het API-token uit het Widget Script. Als JWT vervolgens wordt uitgeschakeld, wordt een nieuw API-token automatisch opnieuw gegenereerd en hersteld in het Widget Script.

Het implementeren van het authenticatie-eindpunt

Na het configureren van JWT in het portaal moet je een authenticatie-endpoint instellen in je backend-applicatie. Dit eindpunt ontvangt een verzoek van de widget en geeft als antwoord een geldig token terug.

Het onderstaande voorbeeld laat zien hoe je het eindpunt in C# kunt implementeren. Dezelfde logica geldt voor andere server-side talen zoals Node.js of Python — pas de HTTP-client- en JSON-serialisatiebibliotheken aan waar nodig.

/// <summary>
/// Endpoint to authenticate a user, generate a JWT token from Document360,
/// and return it to the widget.
/// </summary>
[HttpGet]
[Route("authenticate")]
public async Task<IActionResult> WidgetAuthentication(string id)
{
    // Ensure the user is authenticated in your application
    if (!HttpContext.User.Identity.IsAuthenticated)
    {
        return Unauthorized(new { message = "User is not authenticated." });
    }

    // Define configuration values
    var clientData = new ClientDetails
    {
        ClientId = "{Client ID}",                // Replace with your project's client ID
        Secret = "{Client secret}",              // Replace with your generated client secret
        TokenEndpoint = "{Token endpoint}",      // Replace with the token endpoint URL from Document360
        WidgetId = "{Widget ID}",                // Replace with your widget ID
        SecurityGroupIds = "group1,group2",      // Replace with comma-separated reader group IDs
        TokenValidity = 900                      // Token validity in seconds (300–86400)
    };

    // Return 404 if configuration is missing
    if (clientData == null)
    {
        return NotFound(new { message = "Client configuration not found." });
    }

    // Convert the comma-separated reader group IDs into a list
    List<string> readerGroupIds = null;
    if (!string.IsNullOrEmpty(clientData.SecurityGroupIds))
    {
        readerGroupIds = clientData.SecurityGroupIds
            .Split(',')
            .Select(c => c.Trim())
            .ToList();
    }

    // Prepare the payload with user and configuration details
    var payload = new
    {
        username = "{Username}",                     // Replace with actual user data if available
        firstName = "{First name}",
        lastName = "{Last name}",
        emailId = "{Email address}",
        readerGroupIds = readerGroupIds,
        tokenValidity = clientData.TokenValidity,
        widgetId = clientData.WidgetId,
        projectId = clientData.ClientId
    };

    var payloadString = JsonConvert.SerializeObject(payload);

    try
    {
        // Send request to Document360 token endpoint
        var result = await client.RequestTokenAsync(new TokenRequest
        {
            Address = clientData.TokenEndpoint,
            ClientId = clientData.ClientId,
            ClientSecret = clientData.Secret,
            GrantType = "Widget",
            Parameters = 
            {
                { "payload", payloadString },
                { "id", clientData.ClientId }
            }
        });

        // Return the access token to the widget
        return Ok(new
        {
            accessToken = result.AccessToken,
            expiresIn = result.ExpiresIn
        });
    }
    catch (Exception ex)
    {
        // Handle unexpected errors (optional)
        return StatusCode(500, new
        {
            message = "Failed to generate token.",
            details = ex.Message
        });
    }
}

• De tokenValidity waarde wordt in seconden ingesteld. Het moet tussen de 300 seconden (5 minuten) en 86.400 seconden (1440 minuten) zijn. Als je een waarde buiten dit bereik invoert, past het systeem deze automatisch aan naar de dichtstbijzijnde geldige waarde. Als je bijvoorbeeld 60 seconden (1 minuut) instelttokenValidity, verhoogt het systeem deze tot de minimaal toegestane waarde van 300 seconden (5 minuten). Een waarde van 900 seconden (15 minuten) is een redelijke standaard voor de meeste gebruiksgevallen — kortere waarden verbeteren de beveiliging maar verhogen de backendbelasting.

• De widget vereist ten minste één geldige lezersgroep-ID om de inhoud weer te geven. Neem deze op als een komma-gescheiden lijst in de readerGroupIds parameter van de JWT-payload.

Test je JWT-widgetconfiguratie met Postman

Na het instellen van JWT in het Document360-portaal en het implementeren van je backend-authenticatie-endpoint, kun je Postman gebruiken om te bevestigen dat je configuratie werkt zoals verwacht.

Deze test simuleert wat de widget doet: hij stuurt een verzoek naar je backend om een geldige JWT op te halen.

Stel de test in Postman in

1. Lanceerpostbode.

2. Selecteer + Nieuw tabblad of klik op Nieuw > HTTP-verzoek.

3. Stel de methode in op POST.

4. Voer in het aanvraag-URL-veld de volledige URL van je backend-endpoint in.

   Voorbeeld: https://yourdomain.com/authenticate

5. Ga naar het tabblad Autorisatie .

6. Selecteer onder Type Basic Auth.

7. Voer de volgende kwalificaties in:

   • Gebruikersnaam: Je Client ID van het Document360-portaal.

   • Wachtwoord: Je Client Secret (gegenereerd toen je de JWT aanmaakte).

8. Ga vervolgens naar het tabblad Body om het verzoeklichaam in te stellen.

9. Selecteer raw.

10. Kies JSON in het dropdownmenu aan de rechterkant.

11. Plak het volgende voorbeeld JSON in het lichaam:

    {
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "john.doe@example.com",
      "readerGroupIds": ["group1", "group2"],
      "tokenValidity": 900,
      "widgetId": "your-widget-id",
      "projectId": "your-project-id"
    }

    Vervang de waarden door echte data uit je app en Document360-configuratie.

Als het verzoek succesvol is, ontvang je een JSON-antwoord als volgt:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900
}

• accessToken: Dit is de ondertekende JWT die de widget zal gebruiken om de lezer te autoriseren.

• expiresIn: Tokengeldigheid in seconden (15 minuten = 900 seconden).

Controleer na het verzenden van het verzoek of de responsstatus 200 OK is, wat wijst op een succesvol verzoek. De responsbody moet een geldig accessTokenbevatten , wat de ondertekende JWT is die door de widget wordt gebruikt. Controleer daarnaast dat de expiresIn waarde overeenkomt met de verwachte geldigheidsduur van de token in seconden (bijvoorbeeld 900 seconden voor 15 minuten).

Als al deze waarden correct verschijnen, werkt je JWT-setup zoals bedoeld.

Probleemoplossing

Als het Postman-verzoek of de live widget geen geldig token teruggeeft, raadpleeg dan de veelvoorkomende problemen hieronder.

Volgende stappen

Nadat je JWT-configuratie is geverifieerd en werkt, kun je:

• Embed de widget op je website door het scriptfragment toe te voegen aan het scriptgedeelte van je webpagina.

• Beheer lezerstoegang door lezersgroepopdrachten bij te werken in Connections > Readers.

• Pas het uiterlijk en gedrag van de widget aan vanuit het tabblad Aanpassen in de widget-editor.