> ## 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.
# Configuration de l'authentification
> Contrôlez l’accès à votre documentation en authentifiant les utilisateurs.
Les [offres Pro](https://mintlify.com/pricing?ref=authentication) incluent l’authentification par mot de passe.
Les [offres Custom](https://mintlify.com/pricing?ref=authentication) incluent toutes les méthodes d’authentification.
L’authentification exige que les utilisateurs se connectent avant d’accéder à votre documentation.
## Modes d’authentification
Choisissez entre les modes d’authentification complet ou partiel selon vos besoins en contrôle d’accès.
**Authentification complète** : Toutes les pages sont protégées. Les utilisateurs doivent se connecter avant d’accéder à tout contenu.
**Authentification partielle** : Certaines pages sont publiques, tandis que d’autres nécessitent une authentification. Les utilisateurs peuvent parcourir librement le contenu public et ne s’authentifier que lorsqu’ils accèdent à des pages protégées.
Lors de la configuration de l’une des méthodes de handshake ci‑dessous, sélectionnez **Authentification complète** ou **Authentification partielle** dans les paramètres du Dashboard.
## 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 la personnalisation du contenu.
### Prérequis
* Vos exigences de sécurité autorisent le partage de mots de passe entre utilisateurs.
### Mise en œuvre
1. Dans votre Dashboard, allez sur [Authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Authentification complète** ou **Authentification partielle**.
3. Sélectionnez **Mot de passe**.
4. Saisissez un mot de passe sécurisé.
5. Sélectionnez **Enregistrer les modifications**.
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
1. Dans votre Tableau de bord, accédez à [Authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Authentification complète** ou **Authentification partielle**.
3. Sélectionnez **Mintlify Auth**.
4. Sélectionnez **Activer Mintlify Auth**.
1. Dans votre Tableau de bord, accédez à [Membres](https://dashboard.mintlify.com/settings/organization/members).
2. Ajoutez chaque personne devant avoir accès à votre documentation.
3. 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
1. Dans votre Dashboard, accédez à [Authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Authentification complète** ou **Authentification partielle**.
3. 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.
4. Sélectionnez **Enregistrer les modifications**.
1. Copiez l’**URL de redirection** depuis vos [paramètres d’authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Ajoutez l’URL de redirection comme URL de redirection autorisée dans votre serveur OAuth.
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](/fr/deploy/personalization-setup#user-data-format) pour plus d’informations.
Ajoutez l’URL de cet endpoint dans le champ **Info API URL** de vos [paramètres d’authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
### 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 :
```json theme={null}
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configurez votre serveur OAuth pour autoriser les redirections** vers votre URL de rappel.
### 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
1. Dans votre Dashboard, allez à [Authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Authentification complète** ou **Authentification partielle**.
3. Sélectionnez **JWT**.
4. Saisissez l’URL de votre parcours de connexion existant et sélectionnez **Enregistrer les modifications**.
5. Sélectionnez **Generate new key**.
6. Stockez votre key de manière sécurisée, là où votre backend peut y accéder.
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](/fr/deploy/personalization-setup#user-data-format) 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}`.
```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 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}`);
}
```
```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, '')
@router.get('/auth')
async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
'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 1 semaine
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
'lastName': current_user.last_name,
},
},
key=private_key,
algorithm='EdDSA'
)
return RedirectResponse(url=f'https://docs.foo.com/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, sa destination prévue est conservée dans la redirection vers votre URL de connexion :
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 authentification, redirection vers `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
4. L’utilisateur arrive à sa destination initiale.
## Rendre des pages publiques
Lorsque vous utilisez l’authentification partielle, toutes les pages sont protégées par défaut. 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.
Les groupes sont gérés via les données utilisateur transmises lors de l’authentification.
```json Example user info highlight={2} theme={null}
{
"groups": ["admin", "beta-users"],
"content": {
"firstName": "Jane",
"lastName": "Doe"
}
}
```
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.
### Interaction avec les modes d’authentification
Les groupes fonctionnent différemment selon votre mode d’authentification.
**Authentification complète avec groupes :**
* 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.
```mdx Anyone can view this page theme={null}
---
title: "Guide public"
public: true
---
```
````mdx Only authenticated users can view this page theme={null}
---
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"]
---
````