Configuration de l’authentification

Contrôlez la confidentialité de votre documentation en authentifiant les utilisateurs

Les formules Pro incluent l’authentification par mot de passe.

Les formules Enterprise incluent toutes les méthodes d’authentification.

L’authentification impose aux utilisateurs de se connecter avant d’accéder à votre documentation.

​

Modes d’authentification

Choisissez entre les modes d’authentification complète et partielle en fonction de vos besoins en matière de 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 aux pages protégées.

Lors de la configuration de l’une des méthodes de handshake ci-dessous, vous sélectionnerez soit Authentification complète soit Authentification partielle dans les paramètres de votre Dashboard.

​

Configuration de l’authentification

Sélectionnez la méthode d’échange (handshake) que vous souhaitez configurer.

Mot de passe

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.

​

Mise en œuvre

1. Créer un mot de passe.

   1. Dans votre Dashboard, accédez à Authentification.
   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.
2. Distribuer l’accès.

   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 individuels. Vous souhaitez 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 voilà !

Tableau de bord Mintlify

​

Prérequis

• Les utilisateurs de votre documentation sont aussi vos éditeurs.

​

Mise en œuvre

1. Activer l’authentification du Tableau de bord Mintlify.

   1. Dans votre Tableau de bord Mintlify, accédez à Authentification.
   2. Sélectionnez Authentification complète ou Authentification partielle.
   3. Sélectionnez Mintlify Auth.
   4. Sélectionnez Activer Mintlify Auth.
2. Ajouter des utilisateurs autorisés.

   1. Dans votre Tableau de bord Mintlify, accédez à 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 votre équipe utilise le Tableau de bord Mintlify 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 sont ajoutés à votre organisation.

OAuth 2.0

​

Prérequis

• Un serveur OAuth ou OIDC prenant en charge le flux Authorization Code.
• La possibilité de créer un point de terminaison d’API accessible par des jetons d’accès OAuth (facultatif, pour activer les fonctionnalités de personnalisation).

​

Mise en œuvre

1. Configurez vos paramètres OAuth.

   1. Dans votre Dashboard, accédez à Authentication.
   2. Sélectionnez Full Authentication ou Partial Authentication.
   3. Sélectionnez OAuth et configurez les champs suivants :

   • Authorization URL : votre point de terminaison 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 dans son intégralité (par exemple, pour un scope tel que provider.users.docs, copiez bien provider.users.docs en entier). Utilisez plusieurs scopes si vous avez besoin de niveaux d’accès différents.
   • Token URL : votre point de terminaison d’échange de jeton OAuth.
   • Info API URL (facultatif) : point de terminaison pour récupérer les informations utilisateur à des fins de personnalisation. S’il est omis, le flux OAuth ne servira qu’à 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, redirigez-le vers l’URL de votre documentation.

   4. Sélectionnez Save changes.
2. Configurez votre serveur OAuth.

   1. Copiez l’URL de redirection depuis vos paramètres d’authentification.
   2. Ajoutez cette URL de redirection comme URL de redirection autorisée dans votre serveur OAuth.
3. Créez votre point de terminaison d’informations utilisateur (facultatif).

   Pour activer les fonctionnalités de personnalisation, créez un point de terminaison d’API qui :

   • Accepte les jetons d’accès OAuth pour l’authentification.
   • Retourne les données utilisateur au format User. Voir User data format pour plus d’informations.

   Ajoutez l’URL de ce point de terminaison dans le champ Info API URL de vos paramètres d’authentification.

​

Exemple

Votre documentation est hébergée à l’adresse 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 point de terminaison 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"]
}

Configurez votre serveur OAuth pour autoriser les redirections vers votre URL de callback.

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

1. Générez une clé privée.

   1. Dans votre Dashboard, accédez à Authentication.
   2. Sélectionnez Full Authentication ou Partial Authentication.
   3. Sélectionnez JWT.
   4. Saisissez l’URL de votre flux de connexion existant et sélectionnez Enregistrer les modifications.
   5. Sélectionnez Generate new key.
   6. Stockez votre key en lieu sûr afin qu’elle soit accessible par votre backend.
2. Intégrez l’authentification Mintlify à 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 User data format pour plus d’informations.
   • Signez le JWT avec votre key 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 flux de connexion pour accorder l’accès à la documentation tout en gardant votre documentation distincte 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 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}.

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), // 2 week session expiration
    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') // 10 second JWT expiration
    .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 :

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 est redirigé vers sa destination d’origine.

​

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.

​

Au niveau de la page

Pour rendre une page publique, ajoutez public: true au frontmatter de la page.

Public page example

---
title: "Page publique"
public: true
---

​

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

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"
        ]
      }
    ]
  }
}