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 de toegang tot de ingebedde Document360-widget veilig 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 kennisbank is ingesteld op Privé of Gemengd. In deze gevallen moeten lezers geauthenticeerd zijn voordat de widget inhoud kan tonen. JWT regelt dit stil. 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 toont wat er gebeurt wanneer een gebruiker een widget op je website laadt. De Document360-widget communiceert met je systeem om een beveiligd token te verkrijgen 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 kennisbankwidget bestaan. Zo niet, maak er dan eerst een aan vanuit Connections () > kennisbankwidget. Lees meer op Widget toevoegen.
• De zichtbaarheid van je kennisbasisprojecten 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 minstens één geldige lezergroep-ID om content 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 Geavanceerde instellingen 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 je backend-applicatie. Dit endpoint ontvangt een verzoek van de widget en geeft als antwoord een geldig token terug.

Het onderstaande voorbeeld laat zien hoe het eindpunt in C# geïmplementeerd wordt. Het gebruikt de RequestTokenAsync extensiemethode uit de IdentityModel-bibliotheek. Dezelfde logica geldt voor andere server-side talen zoals Node.js of Python.

using IdentityModel.Client;

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

    // 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
    {
        // Create an HttpClient instance. In production, reuse a single instance
        // (for example, through IHttpClientFactory) instead of creating one per request.
        using var client = new HttpClient();

        // 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 ingesteld in seconden. Het minimum is 300 seconden (5 minuten) en het maximum 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 tokenValidity deze op 60 seconden zet, wordt deze 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-endpoint 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.

Widget-artikelen openen op de kennisbanksite

Wanneer een lezer op het pictogram Openen in nieuw tabblad in de widget klikt, opent het artikel op je kennisbanksite. De widget en de kennisbanksite gebruiken aparte JWT-sessies, waardoor de widgetsessie van de lezer hen niet op de site inloggen.

Als je kennisbank meerdere JWT-configuraties heeft, kan de site niet bepalen welke JWT-aanmelding de lezer moet gebruiken, en ziet de lezer de algemene inlogpagina.

Om lezers direct naar het artikel te leiden, log je ze in op de kennisbank vanuit je eigen applicatie en leid je ze door naar het artikelpad. Voor het URL-formaat, zie Doorverwijzen naar een specifieke pagina na inloggen.

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 lezersgroeptoewijzingen bij te werken in Instellingen > Gebruikers & permissies > Lezers & groepen. Lees meer bij lezersgroepen beheren.
• Pas het uiterlijk en gedrag van de widget aan vanuit het Uiterlijk-paneel onder het tabblad Installatie & Setup 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 het zo kort mogelijk in tokenValidity als je use case toelaat. Kortere geldigheid verkleint 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 client secret opnieuw genereert, update dan alle widgets en chatbots die het delen voordat lezers aan hun volgende sessie beginnen. Het secret wordt gedeeld over 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