Mise en place du JWT SSO

Qu'est-ce qu'un JWT ?

Un jeton web JSON (JWT) est un format de jeton chiffré qui transfère de manière sécurisée des données, telles que des identifiants (authentification et autorisation), entre deux applications. JWT est spécifiquement utilisé pour authentifier les connexions des lecteurs dans Document360. Cliquez ici pour lire à propos de JWT.

SSO d'entreprise utilisant JWT dans Document360

Document360 prend en charge JWT (JSON Web Token) comme l'une de ses méthodes SSO (Single Sign-On), principalement utilisée pour authentifier les connexions des lecteurs. JWT offre un moyen sécurisé de transférer les données d'authentification et d'autorisation entre votre application et la base de connaissances Document360.

Document360 utilise une approche similaire à PKCE (Proof Key for Code Exchange, une méthode OAuth sécurisée) pour générer le jeton JWT .

Choisir la bonne méthode SSO : JWT vs SAML vs OpenID

Document360 prend en charge trois options SSO pour l'authentification des lecteurs : JWT, SAML et OpenID Connect. Le choix de la bonne méthode dépend de la manière dont vous gérez les utilisateurs, de l'infrastructure que vous possédez déjà, et du contrôle nécessaire sur le processus de connexion.

Le tableau ci-dessous compare JWT aux autres options :

Configuration JWT dans Document360

Avant de mettre en œuvre JWT SSO, vous devez d'abord configurer le JWT dans Document360 et obtenir les identifiants nécessaires.

Créer un JWT

Pour créer un JSON Web Token (JWT),

1. Connectez-vous au portail Document360.

2. Va dans ()> Utilisateurs et permissions > JWT.

3. Créez un JWT (secret client) à partir de ici en cliquant sur le bouton Créer JWT .

4. Copiez le secret client généré en cliquant sur l' icône de copier et en cliquant sur Fermer.

NOTE

Le même secret client généré ne sera pas disponible lorsque vous revisiterez cette section. Si nécessaire, le secret du client doit être régénéré.

La page de configuration JWT avec toutes les données est désormais disponible.

Aperçu de la page de configuration JWT

Après la création d'un JWT, la page de configuration du JWT sera visible.

• Configurez votre candidature : Copiez l' ID client, l'URL de rappel, l'URL de génération de code, le secret client, et collez-les dans les champs appropriés de l'application client

• Statut JWT : Activez ou désactivez la connexion SSO JWT pour les lecteurs en utilisant ce bascule. Si le bouton est désactivé, les lecteurs ne pourront pas se connecter au site de la base de connaissances en utilisant leurs identifiants d'application client.

• Supprimer JWT : Cliquez sur le bouton Supprimer pour supprimer le JWT configuré. Vous ne pouvez pas annuler cette action.

• Configuration de base JWT : Coller l'URL de connexion obtenue depuis l'application du client.

  • Les lecteurs atterriront sur la page dédiée de déconnexion pour les lecteurs JWT SSO si aucun lien personnalisé n'est fourni.

Fonctionnement de l'authentification JWT

Le diagramme de haut niveau ci-dessous montre comment obtenir un flux d'authentification JWT dans Document360.

Les étapes ci-dessous expliquent le flux complet d'authentification JWT dans Document360 pour les développeurs configurant le SSO du lecteur via leur propre système de connexion.

Terminologie clé

1. L'utilisateur accède à la base de connaissances privée

   • Lorsqu'un utilisateur tente d'accéder à votre site de base de connaissances, Document360 détecte que JWT SSO est activé et redirige l'utilisateur vers l' URL de connexion configurée dans les paramètres JWT.

2. L'utilisateur se connecte à votre application

   • Si l'utilisateur n'est pas encore authentifié, votre page de connexion gère son authentification.

3. Votre backend demande un code d'authentification à usage unique

   • Après la connexion, votre backend envoie une POST requête à l' URL de génération de code configurée dans Document360 avec les éléments suivants :

     • Identité utilisateur (par exemple, nom, e-mail)

     • Optionnel readerGroupIds

     • tokenValidity en quelques minutes

   • Cette requête doit être autorisée en utilisant l'authentification HTTP Basic avec votre identifiant client et votre secret client.

Exemple d'en-tête d'autorisation

Authorization: Basic Base64Encode(clientId:clientSecret)

Exemple de charge utile JSON

{
  "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
}

NOTE

Assurez-vous de tenir une syntaxe JSON correcte pour éviter les erreurs de configuration.

4. Le serveur Document360 Identity renvoie un code d'authentification

   • Si la requête est valide, le serveur d'identité de Document360 génère un code d'autorisation à usage unique et le renvoie à votre application (backend).

5. Votre application redirige l'utilisateur vers Document360

   • Votre backend ajoute le code à l' URL de rappel et y redirige l'utilisateur.

   • Par exemple : https://yourproject.document360.io/jwt/authorize?code=xyz

NOTE

Le code d'authentification est un code à usage unique et ne peut pas être réutilisé.

6. Document360 valide le code

   • Une fois le code reçu, Document360 l'envoie au serveur d'identité via un backchannel pour l'échanger contre un jeton JWT.

7. Session de lecture créée

   • Document360 extrait les informations utilisateur et les règles d'accès (basées sur readerGroupIds) du jeton.

   • Une session est créée pour le lecteur, lui donnant accès aux catégories, langues ou versions autorisées.

Validité du jeton et comportement de session

• Vous pouvez définir la durée de la session en utilisant le tokenValidity champ dans la charge utile (min : 5 minutes, max : 1440).

• Une fois le jeton expiré :

  • Le lecteur est redirigé vers votre URL de connexion.

  • Si l'utilisateur est toujours authentifié dans votre application, un nouveau code est généré, et la session est rétablie sans interruption.

Liste de contrôle des développeurs

• Configurez l'URL de connexion, l 'URL de rappel et l' URL de génération de code dans les paramètres JWT.

• Générez et stockez en toute sécurité votre secret client (montré une seule fois).

• Configurez la logique backend pour appeler l'URL de génération de code avec une authentification de base.

• Validez et signez le JWT de manière sécurisée dans votre backend.

• Utilisez HTTPS pour tous les points de terminaison.

• Comportement de la session de test, expiration et renouvellement automatique.

• Surveillez les erreurs 401 dues à des codes expirés ou des problèmes de jeton.

Implémentation de la logique de redirection SSO du JWT

Après avoir terminé la configuration JWT dans Document360, votre application a besoin d'une route backend pour gérer la dernière étape du flux de connexion.

Voici l'itinéraire :

• Valide que l'utilisateur est déjà authentifié dans votre application

• Envoie une requête sécurisée à l'URL de génération de code de Document360

• Récupère un code d'autorisation à usage unique

• Redirige l'utilisateur vers le site de la base de connaissances avec ce 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());
        }
    }
}

Test de votre configuration JWT

Une fois que vous avez implémenté la logique SSO JWT dans votre backend, vous pouvez tester l'intégration avec l'un ou cURL l'autre avec Postman. Ces tests simulent la façon dont votre backend communique avec le serveur d'identité Document360 pour récupérer un code d'autorisation à usage unique.

Test de la configuration JWT à l'aide de 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
      }'

Après avoir activé la connexion JWT, le lecteur peut utiliser l'application cliente pour se connecter en tant que compte lecteur sur le site de la base de connaissances Document360.

Test de la configuration JWT avec Postman

Vous pouvez tester votre configuration JWT SSO avec Postman en envoyant manuellement une requête à l'URL de génération de code. Cela vous permet de vérifier que vos identifiants et votre charge utile client sont acceptés et qu'un code d'autorisation à usage unique est généré avec succès.

Pour tester avec Postman, suivez ces étapes :

1. Ouvre Postman et crée une nouvelle demande.

   Réglez la méthode de requête sur POST, et dans le champ URL, entrez l'URL de génération de code depuis l'écran de configuration JWT :

   https://identity.document360.io/api/jwt/generate-code

2. Allez dans l'onglet Autorisation .

3. Définissez le Type à Basic Auth.

4. Dans le champ Nom d'utilisateur , saisissez votre identifiant client.

5. Dans le champ Mot de passe , saisissez votre Secret Client.

6. Naviguez jusqu'à l'onglet Corps .

7. Sélectionnez l'option raw et réglez le format sur JSON.

8. Voici la charge utile JSON requise. Exemple :

   {
     "username": "john.doe",
     "firstName": "John",
     "lastName": "Doe",
     "emailId": "john.doe@example.com",
     "readerGroupIds": ["group1", "group2"],
     "tokenValidity": 15
   }

9. Cliquez sur Envoyer pour soumettre la demande.

Si la configuration est correcte, vous devriez recevoir une 200 OK réponse avec un fichier codeunique . Vous pouvez ensuite utiliser ce code pour rediriger le lecteur vers le site de la base de connaissances et compléter le flux de connexion SSO.

Redirection vers d'autres pages au lieu de la page d'accueil

Par défaut, après la connexion, les utilisateurs sont redirigés vers la page d'accueil de votre base de connaissances.

• Si votre page d'accueil n'est pas publiée, les utilisateurs seront redirigés vers la page /docs .

• Pour rediriger les utilisateurs vers une autre page de votre base de connaissances (autre que les pages Home ou /docs ), configurez la redirection lors de la configuration JWT en utilisant le code suivant.

Motif URL

https://<Knowledge base URL>/jwt/authorize?code=<code>&redirectUrl=<redirect path>

Paramètres

• <URL de la base de connaissances > : L'URL principale de votre site de base de connaissances.

• <Code> : L'identifiant client.

• <chemin de redirection > : La nouvelle URL où vous souhaitez que les utilisateurs atterrissent après la connexion.

Exemple

https://example.document360.io/jwt/authorize?code=FOTaS_SW6dLGytQXvrG_rRFGhyPvrDDrgxJAZzYvJcY&redirectUrl=/docs/5-basic-things-to-get-started

NOTE

• Document360 enverra l' URL de Redirection vers redirectPath le point de terminaison de connexion. Lorsque le point de terminaison de connexion redirige vers la base de connaissances avec le code d'authentification, il doit retourner l' URL de redirection comme redirectUrl paramètre.

• Dans KB Site 2.0, la redirection est gérée via des cookies au lieu du redirectUrl paramètre. Si votre implémentation JWT est basée sur la redirection de chaînes de requête (en utilisant ce redirectUrl paramètre), veuillez noter que l'approche basée sur les cookies ne prend pas en charge ce paramètre. Vous devrez peut-être mettre à jour votre implémentation ou contacter le support pour plus de précisions.

Dépannage

Si vous rencontrez des problèmes lors de la configuration SSO JWT, référez-vous aux erreurs courantes suivantes et à leurs solutions :

Erreur 401 non autorisée lors du test de JWT dans Postman

Erreur : 401 Erreur non autorisée

Si vous rencontrez une erreur 401 non autorisée lors du test de JWT (JSON Web Token) via Postman, cela se produit généralement parce que les paramètres d'autorisation ne sont pas configurés correctement.

Étapes à résoudre :

Pour résoudre cette erreur,

1. Dans Postman, ouvrez la requête que vous testez.

2. Naviguez jusqu'à l'onglet Autorisation .

3. Réglez le type d'autorisation sur Authentification de base.

4. Dans le champ Nom d'utilisateur , saisissez l' ID du client.

5. Dans le champ Mot de passe , saisissez le Secret du client.

6. Va dans l'onglet Corps .

7. Sélectionnez l'option brute dans le menu déroulant et assurez-vous que le format est réglé sur JSON.

8. Ajoutez la charge utile JSON requise pour la requête API.

9. Cliquez sur Envoyer pour exécuter la demande.

Consultez la réponse pour connaître les résultats attendus. Si la requête est acceptée, vous devriez recevoir un code d'authentification ou un jeton dans la réponse.