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 JWT-authenticatie voor widgets werkt
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:
De gebruiker bezoekt je website, waar de Document360-widget is ingebed.
De widget stuurt een stille aanvraag naar je authenticatie-endpoint (token-endpoint) dat in de widget-instellingen is geconfigureerd.
Je backend stuurt een verzoek naar Document360 met de vereiste gegevens (client ID, client secret) en lezersgegevens.
Document360 valideert het verzoek en stuurt een ondertekende JWT terug naar je backend.
Je backend stuurt de token terug naar de widget.
De widget gebruikt dit token om artikelen op te halen en weer te geven waar de lezer toegang toe heeft.
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.
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.
Navigeer naar Connections () > Knowledge base-widget in de linker navigatiebalk.
De lijst met widgets zal verschijnen.
Beweeg je muis over de gewenste widget die je wilt configureren en klik op het pictogram Bewerken () ().
Ga in het tabblad Configureren & verbinden naar de JWT-accordeon en zet de JWT Enable schakelaar aan.
Klant-ID: De client ID is de ID van je project.
Widget-ID: Omdat meerdere widgets kunnen bestaan, wordt een widget-ID verstrekt voor hun unieke doeleinden.
Token-eindpunt: Een token-eindpunt is een HTTP-eindpunt waarmee je een toegangstoken kunt verkrijgen op basis van een autorisatiecode.
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 Clientgeheim is vereist voor JWT-widgets die je kunt maken. Let op: deze informatie wordt niet opgeslagen in Document360.
e. URL autoriseren: Plak de geautoriseerde URL van de widget-webpagina van je kennisbank.
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.
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.
/// <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 = 15 // Token validity in minutes (5–1440)
};
// 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
});
}
}OPMERKING
De
tokenValiditywaarde wordt in enkele minuten vastgesteld. Het moet tussen de 5 minuten (300 seconden) en 1440 minuten (86.400 seconden) zijn. Als je een waarde buiten dit bereik invoert, past het systeem deze automatisch aan naar de dichtstbijzijnde geldige waarde. Als jetokenValiditybijvoorbeeld zet op 1 minuut (60 seconden), verhoogt het systeem deze tot de minimaal toegestane waarde van 5 minuten (300 seconden).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
readerGroupIdsparameter 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
Lanceerpostbode.
Selecteer + Nieuw tabblad of klik op Nieuw > HTTP-verzoek.
Stel de methode in op POST.
Voer in het aanvraag-URL-veld de volledige URL van je backend-endpoint in.
Voorbeeld:
https://yourdomain.com/authenticateGa naar het tabblad Autorisatie .
Selecteer onder Type Basic Auth.
Voer de volgende kwalificaties in:
Gebruikersnaam: Je Client ID van het Document360-portaal.
Wachtwoord: Je Client Secret (gegenereerd toen je de JWT aanmaakte).
Ga vervolgens naar het tabblad Body om het verzoeklichaam in te stellen.
Selecteer raw.
Kies JSON in het dropdownmenu aan de rechterkant.
Plak het volgende voorbeeld JSON in het lichaam:
{ "username": "john.doe", "firstName": "John", "lastName": "Doe", "emailId": "john.doe@example.com", "readerGroupIds": ["group1", "group2"], "tokenValidity": 15, "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.