> ## Documentation Index > Fetch the complete documentation index at: https://smartac-justin-client-exports.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Configuration de l'authentification > Configurez l'authentification utilisateur pour votre site avec OAuth, JWT, mot de passe ou Mintlify Auth afin de contrôler l'accès aux pages et API. L'authentification avec Mintlify Auth est disponible sur toutes les offres. L'authentification par mot de passe, OAuth et JWT nécessite une [offre Enterprise](https://mintlify.com/pricing?ref=authentication). L’authentification exige que les utilisateurs se connectent avant d’accéder à votre contenu. Vous pouvez configurer une authentification complète pour toutes les pages ou une authentification partielle où certaines pages sont publiques et d'autres sont protégées. L'authentification n'est disponible que pour les sites hébergés sur un domaine personnalisé ou un sous-domaine Mintlify. Par exemple, `docs.exemple.com` ou `exemple.mintlify.site`. L'authentification **n'est pas prise en charge** pour les sites avec un [sous-chemin personnalisé](/fr/deploy/docs-subpath). Par exemple, `exemple.com/docs`.
## Configurer l’authentification
Sélectionnez la méthode de poignée de main que vous souhaitez configurer. L'authentification par mot de passe fournit uniquement un contrôle d'accès et ne prend **pas** en charge les fonctionnalités spécifiques aux utilisateurs comme le contrôle d'accès basé sur les groupes ou le pré-remplissage du bac à sable d’API. ### Prérequis du mot de passe * Vos exigences de sécurité autorisent le partage de mots de passe entre les utilisateurs. ### Configuration du mot de passe 1. Dans votre Dashboard, accédez à [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Dans la section **Authentication method**, définissez la visibilité du site sur **Private**. 3. Cliquez sur **Password**. 4. Saisissez un mot de passe sécurisé. 5. Cliquez sur **Save changes**. Après avoir enregistré, 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. Partagez de manière sécurisée le mot de passe et l'URL de la documentation avec les utilisateurs autorisés. ### Exemple de mot de passe 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. ### Prérequis de Mintlify Auth * Toutes les personnes qui doivent accéder à votre documentation doivent être membres de votre organisation Mintlify. ### Configuration de Mintlify Auth 1. Dans votre Dashboard, accédez à [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Dans la section **Authentication method**, définissez la visibilité du site sur **Private**. 3. Cliquez sur **Authenticated**. 4. Cliquez sur **Save changes**. Après avoir enregistré, 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. 1. Dans votre Tableau de bord Mintlify, allez à [Members](https://dashboard.mintlify.com/settings/organization/members). 2. Ajoutez chaque personne qui doit avoir accès à votre documentation. 3. Attribuez des rôles appropriés en fonction de leurs droits de modification. ### Exemple de Mintlify Auth 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. ### Prérequis OAuth 2.0 * Un serveur OAuth ou OIDC qui prend en charge le flux Authorization Code (Authorization Code Flow). * Capacité à créer un endpoint d'API accessible via des jetons d'accès OAuth (facultatif, pour activer le contrôle d'accès basé sur les groupes). ### Configuration OAuth 2.0 1. Dans votre Dashboard, allez dans [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Dans la section **Authentication method**, définissez la visibilité du site sur **Private**. 3. Cliquez sur **Custom**. 4. Cliquez sur **OAuth**. 5. 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. Lorsque les utilisateurs se déconnectent, Mintlify valide la redirection de déconnexion par rapport à l’URL configurée, pour des raisons de sécurité. La redirection ne réussit que si elle correspond exactement à la valeur de `logoutUrl` configurée. Si vous ne configurez pas d’URL de déconnexion, les utilisateurs sont redirigés vers `/login`. Mintlify redirige les utilisateurs avec une requête `GET` et n’ajoute aucun paramètre de requête. Incluez donc directement tous les paramètres (par exemple, `returnTo`) dans l’URL. * **Redirect URL** (facultatif) : L’URL vers laquelle rediriger les utilisateurs après l’authentification. 6. 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. 1. Copiez la **Redirect URL** à partir de vos [paramètres d’authentification](https://dashboard.mintlify.com/products/authentication). 2. Ajoutez cette URL de redirection comme URL de redirection autorisée pour votre serveur OAuth. 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 ` pour l’authentification. * Renvoie les données utilisateur au format `User`. Voir [User data format](#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](https://dashboard.mintlify.com/products/authentication). ### Exemple OAuth 2.0 Vous hébergez votre documentation sur `docs.foo.com` 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 : * **Authorization URL** : `https://auth.foo.com/authorization` * **Client ID** : `ydybo4SD8PR73vzWWd6S0ObH` * **Scopes** : `['provider.users.docs']` * **Token URL** : `https://auth.foo.com/exchange` * **Info API URL** : `https://api.foo.com/docs/user-info` * **Logout URL** : `https://auth.foo.com/logout?returnTo=https%3A%2F%2Fdocs.foo.com` **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 : ```json theme={null} { "groups": ["engineering", "admin"], "expiresAt": 1735689600, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer user_abc123" } } } ``` 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](#user-data-format) pour plus de détails. **Configurez votre serveur OAuth pour autoriser les redirections** vers votre URL de rappel. ### Prérequis JWT * Un système d'authentification capable de générer et de signer des JWT. * Un service backend capable de créer des URL de redirection. ### Configuration JWT 1. Dans votre Dashboard, accédez à [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Dans la section **Authentication method**, définissez la visibilité du site sur **Private**. 3. Cliquez sur **Custom**. 4. Cliquez sur **JWT**. 5. Saisissez l’URL de votre flux de connexion existant. 6. Cliquez sur **Enregistrer les modifications**. 7. Cliquez sur **Générer une nouvelle clé**. 8. 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. 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](#user-data-format) 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. ### Exemple JWT 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 point de terminaison 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}`. ```ts TypeScript theme={null} import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const DOCS_HOST = 'docs.example.com'; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); export async function handleRequest(req: Request, res: Response) { const user = { host: DOCS_HOST, // Doit correspondre à l'URL de votre documentation expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // expiration de session de 2 semaines groups: res.locals.user.groups, apiPlaygroundInputs: { header: { "Authorization": `Bearer ${res.locals.user.apiKey}`, }, }, }; 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_HOST}/login/jwt-callback#${jwt}`); } ``` ```python Python theme={null} import jwt # pyjwt import os from datetime import datetime, timedelta from fastapi.responses import RedirectResponse private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '') DOCS_HOST = 'docs.example.com' @router.get('/auth') async def return_mintlify_auth_status(current_user): jwt_token = jwt.encode( payload={ 'host': DOCS_HOST, # Doit correspondre à l'URL de votre documentation 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # expiration du JWT de 10 secondes 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # expiration de session de 2 semaines 'groups': ['admin'] if current_user.is_admin else [], 'apiPlaygroundInputs': { 'header': { 'Authorization': f'Bearer {current_user.api_key}', }, }, }, key=private_key, algorithm='EdDSA' ) return RedirectResponse(url=f'https://{DOCS_HOST}/login/jwt-callback#{jwt_token}', status_code=302) ``` ### Rediriger les utilisateurs non authentifiés 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. 1. L’utilisateur tente de visiter une page protégée : `https://docs.foo.com/quickstart`. 2. Redirection vers votre URL de connexion avec un paramètre de requête `redirect` : `https://foo.com/docs-login?redirect=%2Fquickstart`. 3. Après l’authentification, redirection vers `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`. 4. L’utilisateur arrive à sa destination d’origine.
## Rendre des pages publiques
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`.
### Pages individuelles
Pour rendre une page publique, ajoutez `public: true` au frontmatter de la page. ```mdx Public page example theme={null} --- title: "Page publique" public: true --- ```
### Groupes de pages
Pour rendre toutes les pages d’un groupe publiques, ajoutez "public": true sous le nom du groupe dans l’objet `navigation` de votre `docs.json`. ```json Public group example theme={null} { "navigation": { "groups": [ { "group": "Groupe public", "public": true, "icon": "play", "pages": [ "quickstart", "installation", "settings" ] }, { "group": "Groupe privé", "icon": "pause", "pages": [ "private-information", "secret-settings" ] } ] } } ```
## Contrôler l’accès avec des groupes
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](#user-data-format) pour plus de détails. ```json Example user info theme={null} { "groups": ["admin", "beta-users"], "expiresAt": 1735689600 } ``` Indiquez quels groupes peuvent accéder à des pages spécifiques à l’aide de la propriété `groups` dans le frontmatter. ```mdx Example page restricted to the admin group highlight={3} theme={null} --- title: "Dashboard administrateur" groups: ["admin"] --- ``` 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.
### Fonctionnement des groupes avec les pages publiques
* Par défaut, toutes les pages nécessitent une authentification. * Les pages comportant une propriété `groups` ne sont accessibles qu’aux utilisateurs authentifiés appartenant à ces groupes. * Les pages sans propriété `groups` sont accessibles à tous les utilisateurs authentifiés. * Les pages avec `public: true` et sans propriété `groups` sont accessibles à tout le monde. ```mdx Page publique theme={null} --- title: "Guide public" public: true --- ``` ```mdx Page protégée theme={null} --- title: "Référence API" --- ``` ```mdx Page protégée avec groupes theme={null} --- title: "Configurations avancées" groups: ["pro", "enterprise"] --- ```
## Format des données utilisateur
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, ainsi que la [personnalisation du contenu](/fr/create/personalization). ```tsx Format theme={null} type User = { host?: string; expiresAt?: number; groups?: string[]; content?: Record; apiPlaygroundInputs?: { server?: Record; header?: Record; query?: Record; cookie?: Record; path?: Record; }; }; ``` ```json Example theme={null} { "host": "docs.example.com", "expiresAt": 1735689600, "groups": ["admin", "beta-users"], "content": { "firstName": "Jane", "company": "Acme Corp" }, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer user_abc123" }, "server": { "baseUrl": "https://api.foo.com" } } } ``` **Requis pour l’authentification JWT.** Le nom d’hôte de votre site de documentation. La chaîne doit correspondre exactement au domaine sur lequel vous déployez votre documentation. Mintlify valide que l’hôte du JWT correspond à l’hôte de la requête afin d’empêcher la réutilisation du jeton sur différents sites. 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. Données personnalisées accessibles dans les pages MDX via la variable `user` pour le [contenu personnalisé](/fr/create/personalization#dynamic-mdx-content). Préremplit les champs du bac à sable d’API avec des valeurs propres à l’utilisateur. Lorsqu’un utilisateur s’authentifie, ces valeurs renseignent les champs de saisie correspondants dans le bac à sable d’API. Les utilisateurs peuvent remplacer les valeurs préremplies, et leurs remplacements sont conservés dans le stockage local. Seules les valeurs qui correspondent au schéma de sécurité du point de terminaison actuel sont appliquées. Valeurs d’en-tête à préremplir, indexées par nom d’en-tête. Valeurs de paramètres de requête à préremplir, indexées par nom de paramètre. Valeurs de cookie à préremplir, indexées par nom de cookie. Valeurs de variables de serveur à préremplir, indexées par nom de variable. Valeurs de paramètres de chemin à préremplir, indexées par nom de paramètre.
## Disponibilité des fonctionnalités
Certaines fonctionnalités se comportent différemment ou ne sont pas disponibles lorsque vous activez l’authentification. Mintlify ne prend pas en charge l’hébergement de fichiers publics arbitraires sur un site authentifié. Tous les fichiers hébergés, y compris `llms.txt`, `llms-full.txt` et `skill.md`, sont soumis aux mêmes exigences d’authentification que vos pages de documentation. | Fonctionnalité | Public | Entièrement authentifié (toutes les pages protégées) | Partiellement authentifié (certaines pages publiques) | | :---------------------------------------------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ | | [llms.txt and llms-full.txt](/fr/ai/llmstxt) | Prise en charge complète | Disponible derrière l’authentification, les outils d’IA peuvent donc ne pas avoir accès aux fichiers | Disponible derrière l’authentification, les outils d’IA peuvent donc ne pas avoir accès aux fichiers | | [MCP server](/fr/ai/model-context-protocol) | Prise en charge complète | Nécessite une authentification pour se connecter | Disponible sans authentification pour les pages publiques et avec authentification pour les pages protégées | | [Markdown export](/fr/ai/markdown-export) | Prise en charge complète | Prise en charge complète, respecte les groupes d’utilisateurs | Prise en charge complète, respecte les groupes d’utilisateurs | | [Export PDF](/fr/optimize/pdf-exports) | Prise en charge complète | Prise en charge complète, respecte les groupes d'utilisateurs. Les pages authentifiées sont exportées avec les images et les ressources incluses. | Prise en charge complète, respecte les groupes d'utilisateurs. Les pages authentifiées sont exportées avec les images et les ressources incluses. | | [Search](/fr/assistant/index) | Prise en charge complète | Prise en charge complète, respecte les groupes d’utilisateurs | Prise en charge complète, respecte les groupes d’utilisateurs | | [Assistant](/fr/assistant/index) | Prise en charge complète | Prise en charge complète, respecte les groupes d’utilisateurs | Prise en charge complète, respecte les groupes d’utilisateurs | | [skill.md](/fr/ai/skillmd) | Prise en charge complète | Non pris en charge | Non pris en charge | | [Sitemap](/fr/optimize/seo#sitemaps-and-robotstxt-files) | Prise en charge complète | Disponible derrière l’authentification, mais exclut les pages dans des groupes | Disponible derrière l’authentification, mais exclut les pages dans des groupes | | [robots.txt](/fr/optimize/seo#sitemaps-and-robotstxt-files) | Prise en charge complète | Disponible derrière l’authentification | Disponible derrière l’authentification |