mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
bbb1a08ed3
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
388 lines
16 KiB
Plaintext
388 lines
16 KiB
Plaintext
---
|
||
title: "Configuration de l'authentification"
|
||
description: "Contrôlez l’accès à votre documentation en authentifiant les utilisateurs."
|
||
keywords: ['authentication', 'auth', 'OAuth', 'JWT', 'password']
|
||
---
|
||
|
||
<Info>
|
||
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.
|
||
</Info>
|
||
|
||
L’authentification exige que les utilisateurs se connectent avant d’accéder à votre documentation.
|
||
|
||
<div id="authentication-modes">
|
||
## Modes d’authentification
|
||
</div>
|
||
|
||
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.
|
||
|
||
<div id="configure-authentication">
|
||
## Configurer l’authentification
|
||
</div>
|
||
|
||
Sélectionnez la méthode de poignée de main que vous souhaitez configurer.
|
||
|
||
<Tabs>
|
||
<Tab title="Mot de passe">
|
||
<Info>
|
||
L’authentification par mot de passe fournit uniquement un contrôle d’accès et ne prend **pas** en charge la personnalisation du contenu.
|
||
</Info>
|
||
|
||
### Prérequis
|
||
|
||
* Vos exigences de sécurité autorisent le partage de mots de passe entre utilisateurs.
|
||
|
||
### Mise en œuvre
|
||
|
||
<Steps>
|
||
<Step title="Créer un mot de passe.">
|
||
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**.
|
||
</Step>
|
||
|
||
<Step title="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.
|
||
</Step>
|
||
</Steps>
|
||
|
||
### 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 !
|
||
</Tab>
|
||
|
||
<Tab title="Tableau de bord Mintlify">
|
||
### Prérequis
|
||
|
||
* Toute personne devant accéder à votre documentation doit être membre de votre organisation Mintlify.
|
||
|
||
### Mise en œuvre
|
||
|
||
<Steps>
|
||
<Step title="Activer l’authentification du Tableau de bord Mintlify.">
|
||
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**.
|
||
</Step>
|
||
|
||
<Step title="Ajouter des utilisateurs autorisés.">
|
||
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.
|
||
</Step>
|
||
</Steps>
|
||
|
||
### 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.
|
||
</Tab>
|
||
|
||
<Tab title="OAuth 2.0">
|
||
### 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
|
||
|
||
<Steps>
|
||
<Step title="Configurez vos paramètres OAuth.">
|
||
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**.
|
||
</Step>
|
||
|
||
<Step title="Configurez votre serveur OAuth.">
|
||
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.
|
||
</Step>
|
||
|
||
<Step title="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](/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).
|
||
</Step>
|
||
</Steps>
|
||
|
||
### 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
|
||
{
|
||
"content": {
|
||
"firstName": "Jane",
|
||
"lastName": "Doe"
|
||
},
|
||
"groups": ["engineering", "admin"]
|
||
}
|
||
```
|
||
|
||
**Configurez votre serveur OAuth pour autoriser les redirections** vers votre URL de rappel.
|
||
</Tab>
|
||
|
||
<Tab title="JWT (JSON Web Token)">
|
||
### 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
|
||
|
||
<Steps>
|
||
<Step title="Générez une clé privée.">
|
||
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.
|
||
</Step>
|
||
|
||
<Step title="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](/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.
|
||
</Step>
|
||
</Steps>
|
||
|
||
### 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}`.
|
||
|
||
<CodeGroup>
|
||
```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)
|
||
```
|
||
</CodeGroup>
|
||
|
||
### 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.
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<div id="make-pages-public">
|
||
## Rendre des pages publiques
|
||
</div>
|
||
|
||
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`.
|
||
|
||
<div id="individual-pages">
|
||
### Pages individuelles
|
||
</div>
|
||
|
||
Pour rendre une page publique, ajoutez `public: true` au frontmatter de la page.
|
||
|
||
```mdx Public page example
|
||
---
|
||
title: "Page publique"
|
||
public: true
|
||
---
|
||
```
|
||
|
||
<div id="groups-of-pages">
|
||
### Groupes de pages
|
||
</div>
|
||
|
||
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
|
||
{
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "Groupe public",
|
||
"public": true,
|
||
"icon": "play",
|
||
"pages": [
|
||
"quickstart",
|
||
"installation",
|
||
"settings"
|
||
]
|
||
},
|
||
{
|
||
"group": "Groupe privé",
|
||
"icon": "pause",
|
||
"pages": [
|
||
"private-information",
|
||
"secret-settings"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
<div id="control-access-with-groups">
|
||
## Contrôler l’accès avec des groupes
|
||
</div>
|
||
|
||
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}
|
||
{
|
||
"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}
|
||
---
|
||
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.
|
||
|
||
<div id="interaction-with-authentication-modes">
|
||
### Interaction avec les modes d’authentification
|
||
</div>
|
||
|
||
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
|
||
---
|
||
title: "Guide public"
|
||
public: true
|
||
---
|
||
```
|
||
|
||
````mdx 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"]
|
||
---
|
||
````
|