> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-add-hello-world-quickstart-48843.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration de l'authentification
> Contrôlez la confidentialité de votre documentation en authentifiant les utilisateurs
Les [offres Pro](https://mintlify.com/pricing?ref=authentication) incluent l’authentification par mot de passe.
Les [offres Enterprise](https://mintlify.com/pricing?ref=authentication) incluent toutes les méthodes d’authentification.
L’authentification requiert que les utilisateurs se connectent avant d’accéder à votre documentation.
## Modes d’authentification
Choisissez entre l’authentification complète ou partielle en fonction de 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 pour accéder aux 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 tableau de bord.
## Configuration de l'authentification
Sélectionnez la méthode de handshake que vous souhaitez configurer.
L'authentification par mot de passe assure uniquement le 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.
### Implémentation
1. Dans votre tableau de bord, accédez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Full Authentication** ou **Partial Authentication**.
3. Sélectionnez **Password**.
4. Saisissez un mot de passe sécurisé.
5. Sélectionnez **Save changes**.
Partagez en toute sécurité 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 individuellement. Vous souhaitez empêcher l’accès public tout en gardant une configuration simple.
**Créez un mot de passe robuste** dans votre tableau de bord. **Partagez les identifiants** avec les utilisateurs autorisés. C’est tout !
### Prérequis
* Les utilisateurs de votre documentation sont aussi vos éditeurs.
### Mise en œuvre
1. Dans votre tableau de bord, accédez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Full Authentication** ou **Partial Authentication**.
3. Sélectionnez **Mintlify Auth**.
4. Sélectionnez **Enable Mintlify Auth**.
1. Dans votre tableau de bord, accédez à [Members](https://dashboard.mintlify.com/settings/organization/members).
2. Ajoutez chaque personne devant avoir accès à votre documentation.
3. Attribuez des rôles adaptés selon leurs droits d’édition.
### Exemple
Votre documentation est hébergée sur `docs.foo.com` et votre équipe utilise le tableau de bord pour modifier vos docs. 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 prenant en charge l’Authorization Code Flow.
* La possibilité de créer un endpoint d’API accessible avec des jetons d’accès OAuth (facultatif, pour activer la personnalisation).
### Mise en œuvre
1. Dans votre tableau de bord, allez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Full Authentication** ou **Partial Authentication**.
3. Sélectionnez **OAuth** et configurez les champs suivants :
* **Authorization URL** : votre endpoint OAuth.
* **Client ID** : l’identifiant de votre client OAuth 2.0.
* **Client Secret** : le secret de votre client OAuth 2.0.
* **Scopes** : permissions à demander. Copiez la chaîne de scopes **entière** (par exemple, pour un scope comme `provider.users.docs`, copiez la totalité de `provider.users.docs`). 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 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 resteront vides.
* **Logout URL** : l’URL de déconnexion native de votre fournisseur OAuth. Si votre fournisseur propose un paramètre `returnTo` ou similaire, faites-le pointer vers l’URL de votre documentation.
4. Sélectionnez **Save changes**.
1. Copiez l’**URL de redirection** depuis vos [paramètres d’authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Ajoutez cette URL comme URL de redirection autorisée dans votre serveur OAuth.
Pour activer la personnalisation, créez un endpoint d’API qui :
* Accepte les jetons d’accès OAuth pour l’authentification.
* Renvoie les données utilisateur au format `User`. Voir [User data format](/fr/authentication-personalization/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 sur `auth.foo.com` qui prend en charge l’Authorization Code Flow.
**Configurez les détails de votre serveur OAuth** dans votre tableau de bord :
* **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 renvoie :
```json
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configurez votre serveur OAuth pour autoriser les redirections** vers votre URL de callback.
### Prérequis
* 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.
### Mise en œuvre
1. Dans votre tableau de bord, allez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Sélectionnez **Full Authentication** ou **Partial Authentication**.
3. Sélectionnez **JWT**.
4. Saisissez l’URL de votre parcours de connexion existant et sélectionnez **Save changes**.
5. Sélectionnez **Generate new key**.
6. Stockez votre clé en toute sécurité, à un emplacement accessible par votre backend.
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`. Voir [User data format](/fr/authentication-personalization/personalization-setup#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 fragment.
### Exemple
Votre documentation est hébergée sur `docs.foo.com` et votre système d’authentification existant sur `foo.com`. Vous souhaitez étendre votre parcours de connexion pour accorder l’accès à la documentation tout en la gardant séparée de votre tableau de bord (ou si vous n’avez pas de tableau de bord).
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 Mintlify.
* Signez le JWT et redirigez vers `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`.
```ts TypeScript
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
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 l’authentification, redirection vers `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
4. L’utilisateur est redirigé vers 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 rendre certaines pages accessibles sans authentification au niveau de la page ou du groupe avec la propriété `public`.
### Niveau de la page
Pour rendre une page publique, ajoutez `public: true` au front matter de la page.
```mdx Exemple de page publique
---
title: "Page publique"
public: true
---
```
### Niveau de groupe
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 Exemple de groupe public
{
"navigation": {
"groups": [
{
"group": "Groupe public",
"public": true,
"icon": "play",
"pages": [
"quickstart",
"installation",
"settings"
]
},
{
"group": "Groupe privé"
"icon": "pause",
"pages": [
"private-information",
"secret-settings"
]
}
]
}
}
```