Configureer JWT voor de knowledge base-widget

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.

Hoe JWT-authenticatie werkt voor de widget

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 stilzwijgend. Lezers zien nooit een apart inlogscherm.

Gebruik JWT voor de widget 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.

Overzicht van authenticatieflow

Het bovenstaande 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.

Het bovenstaande sequentiediagram geeft de technische flow weer 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).

Voordat je begint

• Je moet een rol als projecteigenaar of beheerder hebben in Document360.
• Er moet al minstens één kennisbasis-widget bestaan. Zo niet, maak er dan eerst een aan vanuit de Connections > Knowledge Base-widget. Lees meer bij Widget toevoegen.
• De zichtbaarheid van je kennisbasisproject moet op Privé of Gemengd staan. JWT is niet vereist voor openbare projecten.
• Je moet toegang hebben 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 moet minstens één lezersgroep in je project zijn geconfigureerd. De widget vereist ten minste één geldige lezersgroep-ID om de inhoud weer te geven. Lees meer over JWT-lezersgroepen.

Stap 1: Schakel JWT in en configureer JWT voor de widget

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

   De lijst met widgets verschijnt.

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

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

De volgende velden worden weergegeven:

4. Klik op Opslaan om de wijzigingen toe te passen.

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

Stap 2: Implementeer het authenticatie-endpoint

Na het configureren van JWT in het portaal, stel je een authenticatie-endpoint in 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.

/// <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}",
        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)
    {
        return StatusCode(500, new
        {
            message = "Failed to generate token.",
            details = ex.Message
        });
    }
}

Tokengeldigheidsregels:

• De tokenValidity waarde wordt in seconden ingesteld. Het minimum is 300 seconden (5 minuten) en het maximum is 86.400 seconden (1440 minuten).
• Als je een waarde buiten dit bereik invoert, past het systeem deze automatisch aan naar de dichtstbijzijnde geldige waarde. Bijvoorbeeld, als je het op 60 seconden zet tokenValidity , wordt het automatisch verhoogd naar 300 seconden.
• Een waarde van 900 seconden (15 minuten) is een redelijke standaard voor de meeste gebruiksgevallen. Kortere waarden verbeteren de beveiliging, maar verhogen de backendbelasting.

Stap 3: Test je JWT-widgetconfiguratie met Postman

Nadat je JWT in het portaal hebt ingesteld en je backend-authenticatie-endpoint hebt geïmplementeerd, gebruik je Postman om te bevestigen dat je configuratie werkt zoals verwacht. Deze test verifieert dat het backend-eindpunt van je widget een geldige JWT-token teruggeeft.

1. Lanceerpostbode.

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

3. Zet de methode 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 werd gegenereerd toen je de JWT aanmaakte.

8. Ga naar het tabblad Lichaam .

9. Selecteer raw en kies JSON uit het dropdownmenu.

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

11. Klik op verzenden.

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

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

Controleer het volgende in het antwoord:

• De responsstatus is 200 OK.
• Het responslichaam bevat een geldig accessToken.
• De expiresIn waarde komt overeen met je verwachte tokengeldigheidsduur in enkele seconden.

Als alle drie correct zijn, werkt je JWT-widgetconfiguratie zoals bedoeld.

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 lezergroeptoewijzingen bij te werken in Instellingen > Gebruikers & permissies > Lezers & groepen. Lees meer bij het beheren van lezersgroepen.
• Pas het uiterlijk en gedrag van de widget aan vanuit het tabblad Aanpassen in de widget-editor. Lees meer over het aanpassen van de widget.

Best practices

• Sla het cliëntgeheim op in een beveiligde geheimenbeheerder, niet in broncode of omgevingsbestanden die voor versiebeheer zijn toegewijd.
• Stel tokenValidity het zo kort mogelijk in als je use case toelaat. Kortere geldigheid verkort het blootstellingsvenster als een token wordt onderschept.
• Test altijd met Postman voordat je live gaat om problemen met de credential of payload vroeg te ontdekken.
• Als je het cliëntgeheim opnieuw genereert, update dan alle widgets en chatbots die het delen voordat lezers aan hun volgende sessie beginnen. Het geheim wordt gedeeld door alle JWT-geschikte widgets en chatbots in het project.
• Gebruik lezersgroep-ID's om inhoudsbeperkingen op tokenniveau af te dwingen, zodat lezers alleen zien waar ze toegang toe hebben.

FAQ