Contrôlez l’accès à votre documentation en authentifiant les utilisateurs.
Les offres Pro incluent l’authentification par mot de passe.Les offres Custom incluent toutes les méthodes d’authentification.
L’authentification exige que les utilisateurs se connectent avant d’accéder à votre documentation.Lorsque vous activez l’authentification, les utilisateurs doivent se connecter pour accéder à l’ensemble du contenu. Vous pouvez définir certaines pages ou certains groupes comme publics tout en gardant les autres pages protégées.
Dans la section Password Protection, saisissez un mot de passe sécurisé
Après avoir saisi un mot de passe, votre site est redéployé. Une fois le déploiement terminé, toute personne visitant votre site doit entrer le mot de passe pour accéder à votre contenu.
2
Distribuer l'accès.
Partagez de manière sécurisée le mot de passe et l’URL de la documentation avec les utilisateurs autorisés.
Vous hébergez votre documentation sur docs.foo.com et vous avez besoin d’un contrôle d’accès de base sans suivi des utilisateurs individuels. Vous voulez empêcher l’accès public tout en gardant la configuration simple.Créez un mot de passe robuste dans votre Dashboard. Partagez les identifiants de connexion avec les utilisateurs autorisés. C’est tout !
Activer l’authentification via le Tableau de bord Mintlify.
Dans votre Tableau de bord Mintlify, allez à Authentication.
Activez l’authentification.
Dans la section Custom Authentication, cliquez sur Mintlify Auth.
Cliquez sur Enable Mintlify Auth.
Après avoir activé l’authentification Mintlify, votre site est redéployé. Lorsque le déploiement est terminé, toute personne qui visite votre site doit se connecter à votre organisation Mintlify pour accéder à votre contenu.
2
Ajouter des utilisateurs autorisés.
Dans votre Tableau de bord Mintlify, allez à Members.
Ajoutez chaque personne qui doit avoir accès à votre documentation.
Attribuez des rôles appropriés en fonction de leurs droits de modification.
Vous hébergez votre documentation sur docs.foo.com et toute votre équipe a accès à votre Tableau de bord Mintlify. Vous souhaitez restreindre l’accès aux seuls membres de l’équipe.Activez l’authentification Mintlify dans les paramètres de votre Tableau de bord Mintlify.Vérifiez l’accès de l’équipe en vous assurant que tous les membres de l’équipe sont actifs dans votre organisation.
Dans la section Custom Authentication, cliquez sur OAuth.
Configurez les champs suivants :
Authorization URL : Votre endpoint OAuth.
Client ID : Votre identifiant client OAuth 2.0.
Client Secret : Votre secret client OAuth 2.0.
Scopes (facultatif) : Autorisations à demander. Copiez la chaîne de scope entière (par exemple, pour un scope comme provider.users.docs, copiez l’intégralité de provider.users.docs). Utilisez plusieurs scopes si vous avez besoin de niveaux d’accès différents.
Additional authorization parameters (facultatif) : Paramètres de requête supplémentaires à ajouter à la requête d’autorisation initiale.
Token URL : Votre endpoint d’échange de jeton OAuth.
Info API URL (facultatif) : Endpoint sur votre serveur que Mintlify appelle pour récupérer les informations utilisateur. Requis pour le contrôle d’accès basé sur les groupes. S’il est omis, le flux OAuth vérifie uniquement l’identité.
Logout URL (facultatif) : L’URL de déconnexion native de votre fournisseur OAuth. Mintlify redirige les utilisateurs vers cette URL avec une requête GET lorsqu’ils se déconnectent. Mintlify n’ajoute pas de paramètres de requête, incluez donc directement tous les paramètres (par exemple, returnTo) dans l’URL. Configurez une page vers laquelle rediriger les utilisateurs après une déconnexion réussie.
Redirect URL (facultatif) : L’URL vers laquelle rediriger les utilisateurs après l’authentification.
Cliquez sur Enregistrer les modifications.
Une fois vos paramètres OAuth configurés, votre site est redéployé. Quand le déploiement est terminé, toute personne qui visite votre site doit se connecter à votre fournisseur OAuth pour accéder à votre contenu.
Pour activer le contrôle d’accès basé sur les groupes, créez un endpoint d’API qui :
Répond aux requêtes GET.
Accepte un en-tête Authorization: Bearer <access_token> pour l’authentification.
Renvoie les données utilisateur au format User. Voir User data format pour plus d’informations.
Mintlify appelle cet endpoint avec le jeton d’accès OAuth pour récupérer les informations utilisateur. Aucun paramètre de requête supplémentaire n’est envoyé.Ajoutez l’URL de cet endpoint dans le champ Info API URL de vos paramètres d’authentification.
Vous hébergez votre documentation sur foo.com/docs et vous disposez d’un serveur OAuth existant sur auth.foo.com qui prend en charge le flux « Authorization Code ».Configurez les détails de votre serveur OAuth dans votre Dashboard :
Créez un endpoint d’informations utilisateur à api.foo.com/docs/user-info, qui requiert un jeton d’accès OAuth avec le scope provider.users.docs, et renvoie :
Contrôlez la durée de la session avec le champ expiresAt dans votre réponse d’informations utilisateur. Il s’agit d’un horodatage Unix (en secondes depuis l’époque Unix) indiquant quand la session doit expirer. Consultez le format des données utilisateur pour plus de détails.
Configurez votre serveur OAuth pour autoriser les redirections vers votre URL de rappel.
Dans la section Custom Authentication, cliquez sur JWT.
Saisissez l’URL de votre flux de connexion existant.
Cliquez sur Enregistrer les modifications.
Cliquez sur Générer une nouvelle clé.
Stockez votre clé en toute sécurité, là où votre backend peut y accéder.
Après avoir généré une clé privée, votre site est redéployé. Une fois le déploiement terminé, toute personne qui visite votre site doit se connecter à votre système d’authentification JWT pour accéder à votre contenu.
2
Intégrez l’authentification Mintlify dans votre flux de connexion.
Modifiez votre flux de connexion existant pour inclure ces étapes après l’authentification de l’utilisateur :
Créez un JWT contenant les informations de l’utilisateur authentifié au format User. Voir Format des données utilisateur pour plus d’informations.
Signez le JWT avec votre clé secrète, en utilisant l’algorithme EdDSA.
Créez une URL de redirection vers le chemin /login/jwt-callback de votre documentation, en incluant le JWT comme hash.
Vous hébergez votre documentation sur docs.foo.com avec un système d’authentification existant sur foo.com. Vous voulez étendre votre flux de connexion pour accorder l’accès à la documentation tout en gardant votre documentation séparée de votre Dashboard (ou vous n’avez pas de Dashboard).Créez un endpoint de connexion à https://foo.com/docs-login qui étend votre authentification existante.Après vérification des identifiants de l’utilisateur :
Générez un JWT avec les données utilisateur au format de Mintlify.
Signez le JWT et redirigez vers https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}.
Signaler un code incorrect
Copier
Demander à l'IA
import * as jose from 'jose';import { Request, Response } from 'express';const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // expiration de session de 2 semaines groups: res.locals.user.groups, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'EdDSA' }) .setExpirationTime('10 s') // expiration du JWT de 10 secondes .sign(signingKey); return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);}
Lorsqu’un utilisateur non authentifié tente d’accéder à une page protégée, la redirection vers votre URL de connexion préserve la destination souhaitée par l’utilisateur.
L’utilisateur tente de visiter une page protégée : https://docs.foo.com/quickstart.
Redirection vers votre URL de connexion avec un paramètre de requête redirect : https://foo.com/docs-login?redirect=%2Fquickstart.
Après l’authentification, redirection vers https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}.
Lorsque vous utilisez l’authentification, toutes les pages nécessitent par défaut une authentification pour y accéder. Vous pouvez autoriser l’accès à certaines pages sans authentification, au niveau de la page ou du groupe, à l’aide de la propriété public.
Lorsque vous utilisez l’authentification OAuth ou des JWT (JSON Web Tokens), vous pouvez restreindre certaines pages à des groupes d’utilisateurs spécifiques. C’est utile si vous souhaitez que différents utilisateurs voient des contenus différents selon leur rôle ou leurs attributs.Gérez les groupes via les données utilisateur transmises lors de l’authentification. Voir Format des données utilisateur pour plus de détails.
Les utilisateurs doivent appartenir à au moins un des groupes répertoriés pour accéder à la page. Si un utilisateur tente d’accéder à une page sans le groupe requis, il recevra une erreur 404.
Lorsque vous utilisez l’authentification OAuth ou JWT, votre système renvoie des données utilisateur qui contrôlent la durée de la session et l’appartenance à des groupes pour le contrôle d’accès.
Signaler un code incorrect
Copier
Demander à l'IA
type User = { expiresAt?: number; groups?: string[];};
Heure d’expiration de la session, en secondes depuis l’époque Unix. Lorsque l’heure actuelle dépasse cette valeur, l’utilisateur doit s’authentifier de nouveau.
Pour les JWT : cela diffère de la revendication exp d’un JWT, qui détermine le moment où un JWT est considéré comme invalide. Par mesure de sécurité, définissez la revendication exp du JWT sur une durée courte (10 secondes ou moins). Utilisez expiresAt pour la durée réelle de la session (de quelques heures à plusieurs semaines).
Liste des groupes auxquels l’utilisateur appartient. Les pages dont le champ groups dans le frontmatter contient une valeur correspondante sont accessibles à cet utilisateur.Exemple : Un utilisateur avec groups: ["admin", "engineering"] peut accéder aux pages étiquetées avec admin ou engineering dans leur champ groups du frontmatter.
