mintlify__docs/fr/deploy/authentication-setup.mdx

---
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 Enterprise](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.

Lorsque vous activez l’authentification, les utilisateurs doivent se connecter pour accéder à l’ensemble du contenu. Vous pouvez définir certaines pages ou certains groupes comme publics tout en gardant les autres pages protégées.

<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&#39;authentification par mot de passe fournit uniquement un contrôle d&#39;accès et ne prend **pas** en charge les fonctionnalités spécifiques aux utilisateurs comme le contrôle d&#39;accès basé sur les groupes ou le pré-remplissage du bac à sable d’API.
    </Info>

    ### Prérequis

    * Vos exigences de sécurité autorisent le partage de mots de passe entre les utilisateurs.

    ### Configuration

    <Steps>
      <Step title="Créer un mot de passe.">
        1. Dans votre Dashboard, accédez à [Authentication](https://dashboard.mintlify.com/products/authentication).
        2. Activez l&#39;authentification.
        3. Dans la section **Password Protection**, saisissez un mot de passe sécurisé

        Après avoir saisi un mot de passe, 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.
      </Step>

      <Step title="Distribuer l'accès.">
        Partagez de manière sécurisée le mot de passe et l&#39;URL de la documentation avec les utilisateurs autorisés.
      </Step>
    </Steps>

    ### Exemple

    Vous hébergez votre documentation sur `docs.foo.com` et vous avez besoin d&#39;un contrôle d&#39;accès de base sans suivi des utilisateurs individuels. Vous voulez empêcher l&#39;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. C&#39;est tout !
  </Tab>

  <Tab title="Tableau de bord Mintlify">
    ### Prérequis

    * Toutes les personnes qui doivent accéder à votre documentation doivent être membres de votre organisation Mintlify.

    ### Configuration

    <Steps>
      <Step title="Activer l’authentification via le Tableau de bord Mintlify.">
        1. Dans votre Dashboard, accédez à [Authentication](https://dashboard.mintlify.com/products/authentication).
        2. Activez l’authentification.
        3. Dans la section **Custom Authentication**, cliquez sur **Mintlify Auth**.
        4. Cliquez sur **Enable Mintlify Auth**.

        Après avoir activé l’authentification Mintlify, 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.
      </Step>

      <Step title="Ajouter des utilisateurs autorisés.">
        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.
      </Step>
    </Steps>

    ### Exemple

    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.
  </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 par des jetons d’accès OAuth (facultatif, pour activer le contrôle d’accès basé sur les groupes).

    ### Configuration

    <Steps>
      <Step title="Configurez vos paramètres OAuth.">
        1. Dans votre Dashboard, allez dans [Authentication](https://dashboard.mintlify.com/products/authentication).
        2. Activez l’authentification.
        3. Dans la section **Custom Authentication**, cliquez sur **OAuth**.
        4. 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.

        5. 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.
      </Step>

      <Step title="Configurez votre serveur OAuth.">
        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.
      </Step>

      <Step title="Créez votre endpoint d’informations utilisateur (facultatif).">
        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 <access_token>` 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).
      </Step>
    </Steps>

    ### Exemple

    Vous hébergez votre documentation sur `foo.com/docs` 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%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
    {
      "groups": ["engineering", "admin"],
      "expiresAt": 1735689600,
      "apiPlaygroundInputs": {
        "header": {
          "Authorization": "Bearer user_abc123"
        }
      }
    }
    ```

    <Note>
      Contrôlez la durée de la session avec le champ `expiresAt` dans votre réponse d&#39;informations utilisateur. Il s&#39;agit d&#39;un horodatage Unix (en secondes depuis l&#39;époque Unix) indiquant quand la session doit expirer. Consultez le [format des données utilisateur](#user-data-format) pour plus de détails.
    </Note>

    **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.
    * Un service backend capable de créer des URL de redirection.

    ### Configuration

    <Steps>
      <Step title="Générez une clé privée.">
        1. Dans votre Dashboard, accédez à [Authentication](https://dashboard.mintlify.com/products/authentication).
        2. Activez l’authentification.
        3. Dans la section **Custom Authentication**, cliquez sur **JWT**.
        4. Saisissez l’URL de votre flux de connexion existant.
        5. Cliquez sur **Enregistrer les modifications**.
        6. Cliquez sur **Générer une nouvelle clé**.
        7. 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.
      </Step>

      <Step title="Intégrez l’authentification Mintlify dans votre flux de connexion.">
        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.
      </Step>
    </Steps>

    ### Exemple

    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 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 de 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,
          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.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 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.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, 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.
  </Tab>
</Tabs>

<div id="make-pages-public">
  ## Rendre des pages publiques
</div>

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`.

<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 &quot;public&quot;: 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.

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
{
  "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}
---
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="how-groups-interact-with-public-pages">
  ### Fonctionnement des groupes avec les pages publiques
</div>

* 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.

<CodeGroup>
  ```mdx Page publique
  ---
  title: "Guide public"
  public: true
  ---
  ```

  ```mdx Page protégée
  ---
  title: "Référence API"
  ---
  ```

  ```mdx Page protégée avec groupes
  ---
  title: "Configurations avancées"
  groups: ["pro", "enterprise"]
  ---
  ```
</CodeGroup>

<div id="user-data-format">
  ## Format des données utilisateur
</div>

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).

<CodeGroup>
  ```tsx Format
  type User = {
    expiresAt?: number;
    groups?: string[];
    content?: Record<string, any>;
    apiPlaygroundInputs?: {
      server?: Record<string, string>;
      header?: Record<string, unknown>;
      query?: Record<string, unknown>;
      cookie?: Record<string, unknown>;
    };
  };
  ```

  ```json Example
  {
    "expiresAt": 1735689600,
    "groups": ["admin", "beta-users"],
    "content": {
      "firstName": "Jane",
      "company": "Acme Corp"
    },
    "apiPlaygroundInputs": {
      "header": {
        "Authorization": "Bearer user_abc123"
      },
      "server": {
        "baseUrl": "https://api.foo.com"
      }
    }
  }
  ```
</CodeGroup>

<ParamField path="expiresAt" type="number">
  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.

  <Warning>**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).</Warning>
</ParamField>

<ParamField path="groups" type="string[]">
  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.
</ParamField>

<ParamField path="content" type="Record<string, any>">
  Données personnalisées accessibles dans les pages MDX via la variable `user` pour le [contenu personnalisé](/fr/create/personalization#dynamic-mdx-content).
</ParamField>

<ParamField path="apiPlaygroundInputs" type="object">
  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.

  <Expandable title="propriétés">
    <ParamField path="header" type="Record<string, unknown>">
      Valeurs d’en-tête à préremplir, indexées par nom d’en-tête.
    </ParamField>

    <ParamField path="query" type="Record<string, unknown>">
      Valeurs de paramètres de requête à préremplir, indexées par nom de paramètre.
    </ParamField>

    <ParamField path="cookie" type="Record<string, unknown>">
      Valeurs de cookie à préremplir, indexées par nom de cookie.
    </ParamField>

    <ParamField path="server" type="Record<string, string>">
      Valeurs de variables de serveur à préremplir, indexées par nom de variable.
    </ParamField>
  </Expandable>
</ParamField>