Documentation Index
Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
Use this file to discover all available pages before exploring further.
Les offres Pro incluent l’authentification par mot de passe.Les offres Custom incluent toutes les méthodes d’authentification. Mot de passe
Tableau de bord Mintlify
OAuth 2.0
JWT (JSON Web Token)
L’authentification par mot de passe fournit uniquement un contrôle d’accès et ne prend pas en charge la personnalisation du contenu.
Prérequis
- Vos exigences de sécurité autorisent le partage de mots de passe entre utilisateurs.
Mise en œuvre
Créer un mot de passe.
- Dans votre Dashboard, allez sur Authentification.
- Sélectionnez Authentification complète ou Authentification partielle.
- Sélectionnez Mot de passe.
- Saisissez un mot de passe sécurisé.
- Sélectionnez Enregistrer les modifications.
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.
Exemple
Votre documentation est hébergée sur docs.foo.com et vous avez besoin d’un contrôle d’accès simple sans suivi des utilisateurs individuels. Vous voulez empêcher l’accès public tout en gardant une configuration simple.Créez un mot de passe robuste dans votre Dashboard. Partagez les identifiants avec les utilisateurs autorisés. Et c’est tout !Prérequis
- Toute personne devant accéder à votre documentation doit être membre de votre organisation Mintlify.
Mise en œuvre
Activer l’authentification du Tableau de bord Mintlify.
- Dans votre Tableau de bord, accédez à Authentification.
- Sélectionnez Authentification complète ou Authentification partielle.
- Sélectionnez Mintlify Auth.
- Sélectionnez Activer Mintlify Auth.
Ajouter des utilisateurs autorisés.
- Dans votre Tableau de bord, accédez à Membres.
- Ajoutez chaque personne devant avoir accès à votre documentation.
- Attribuez des rôles appropriés en fonction de leurs droits d’édition.
Exemple
Votre documentation est hébergée sur docs.foo.com et toute votre équipe a accès à votre Tableau de bord. 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.Vérifiez l’accès de l’équipe en vous assurant que tous les membres de l’équipe sont ajoutés à votre organisation.Prérequis
- Un serveur OAuth ou OIDC qui prend en charge le flux Authorization Code.
- La possibilité de créer un endpoint d’API accessible via des jetons d’accès OAuth (facultatif, pour activer les fonctionnalités de personnalisation).
Implémentation
Configurez vos paramètres OAuth.
- Dans votre Dashboard, accédez à Authentification.
- Sélectionnez Authentification complète ou Authentification partielle.
- Sélectionnez OAuth et configurez ces champs :
- Authorization URL : votre endpoint OAuth.
- Client ID : votre identifiant client OAuth 2.0.
- Client Secret : votre secret client OAuth 2.0.
- Scopes : autorisations à demander. Copiez la chaîne de scope entière (par exemple, pour un scope comme
provider.users.docs, copiez le provider.users.docs complet). Utilisez plusieurs scopes si vous avez besoin de niveaux d’accès différents.
- 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 à des fins de personnalisation. S’il est omis, le flux OAuth servira uniquement à vérifier l’identité et les informations utilisateur seront vides.
- Logout URL : l’URL de déconnexion native de votre fournisseur OAuth. Si votre fournisseur dispose d’un paramètre
returnTo ou similaire, faites-le pointer vers l’URL de votre documentation.
- Sélectionnez Enregistrer les modifications.
Configurez votre serveur OAuth.
- Copiez l’URL de redirection depuis vos paramètres d’authentification.
- Ajoutez l’URL de redirection comme URL de redirection autorisée dans votre serveur OAuth.
Créez votre endpoint d’informations utilisateur (facultatif).
Pour activer les fonctionnalités de personnalisation, créez un endpoint d’API qui :
- Accepte les jetons d’accès OAuth pour l’authentification.
- Retourne les données utilisateur au format
User. Voir Format des données utilisateur pour plus d’informations.
Ajoutez l’URL de cet endpoint dans le champ Info API URL de vos paramètres d’authentification. Exemple
Votre documentation est hébergée sur foo.com/docs et vous disposez d’un serveur OAuth existant à 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%2Ffoo.com%2Fdocs
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 retourne :{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
Prérequis
- Un système d’authentification capable de générer et de signer des JWT (JSON Web Token).
- Un service backend capable de créer des URL de redirection.
Implémentation
Générez une clé privée.
- Dans votre Dashboard, allez à Authentification.
- Sélectionnez Authentification complète ou Authentification partielle.
- Sélectionnez JWT.
- Saisissez l’URL de votre parcours de connexion existant et sélectionnez Enregistrer les modifications.
- Sélectionnez Generate new key.
- Stockez votre key de manière sécurisée, là où votre backend peut y accéder.
Intégrez l’authentification Mintlify à votre parcours de connexion.
Modifiez votre parcours 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. Consultez Format des données utilisateur pour en savoir plus.
- 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 dans le hash.
Exemple
Votre documentation est hébergée sur docs.foo.com avec un système d’authentification existant sur foo.com. Vous souhaitez étendre votre parcours de connexion pour accorder l’accès à la documentation tout en gardant celle-ci séparée de votre Dashboard (ou si vous n’avez pas de Dashboard).Créez un endpoint de connexion à https://foo.com/docs-login qui étend votre authentification existante.Après la vérification des identifiants utilisateur :
- Générez un JWT avec des données utilisateur au format Mintlify.
- Signez le JWT et redirigez vers
https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}.
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,
content: {
firstName: res.locals.user.firstName,
lastName: res.locals.user.lastName,
},
};
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}`);
}
Rediriger les utilisateurs non authentifiés
Lorsqu’un utilisateur non authentifié tente d’accéder à une page protégée, sa destination prévue est conservée dans la redirection vers votre URL de connexion :
- 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 authentification, redirection vers
https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}.
- L’utilisateur arrive à sa destination initiale.
Rendre des pages publiques
public.
Pour rendre une page publique, ajoutez public: true au frontmatter de la page.
---
title: "Page publique"
public: true
---
navigation de votre docs.json.
{
"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
{
"groups": ["admin", "beta-users"],
"content": {
"firstName": "Jane",
"lastName": "Doe"
}
}
groups dans le frontmatter.
Example page restricted to the admin group
---
title: "Dashboard administrateur"
groups: ["admin"]
---
Interaction avec les modes d’authentification
- Toutes les pages nécessitent une authentification.
- Les pages sans propriété
groups sont accessibles à tous les utilisateurs authentifiés.
- Les pages avec une propriété
groups ne sont accessibles qu’aux utilisateurs authentifiés appartenant à ces groupes.
Authentification partielle avec groupes :
- Les pages nécessitent une authentification, sauf si vous les rendez publiques.
- Les pages avec
public: true et sans groups sont accessibles à tout le monde.
- Les pages avec
groups (avec ou sans public: true) ne sont accessibles qu’aux utilisateurs authentifiés appartenant à ces groupes.
Anyone can view this page
---
title: "Guide public"
public: true
---
Only authenticated users can view this page
---
title: "Référence API"
---
```mdx Seuls les utilisateurs authentifiés des groupes pro ou enterprise peuvent consulter cette page
---
title: "Configurations avancées"
groups: ["pro", "enterprise"]
---
