Configuration d’un backend personnalisé

Configurez un écran de connexion personnalisé pour les visiteurs de vos docs.

Ce guide vous explique comment configurer un écran de connexion protégé pour vos documents. Avant de suivre ce guide, assurez-vous d'avoir d'abord suivi le processus d'activation de l'accès authentifié.

Ce guide vous explique comment configurer un écran de connexion protégé pour votre site de documentation GitBook en utilisant votre propre backend d'authentification personnalisé.

Si vous utilisez l'un des fournisseurs d'authentification que nous prenons en charge ou si vous disposez d'un backend conforme à OpenID Connect (OIDC), consultez nos guides d'intégration pour une configuration plus simple : Auth0 | Azure AD | Okta | AWS Cognito | OIDC

Aperçu

Pour configurer un système d'authentification personnalisé pour votre site GitBook, suivez ces étapes clés :

Créez un backend personnalisé pour authentifier vos utilisateurs

Implémentez un backend qui invite les utilisateurs à se connecter et les authentifie.

Signez et transmettez un jeton JWT à GitBook

Créez un jeton JWT et signez-le avec la clé privée de votre site.

Configurez une URL de secours

Configurez une URL à utiliser lorsqu'un visiteur non authentifié accède à votre site.

Configurez un accès authentifié multi-locataires (optionnel)

Configurez votre backend pour gérer l'authentification sur plusieurs sites GitBook.

Configurez votre backend pour du contenu adaptatif (optionnel)

Configurez votre backend pour fonctionner avec du contenu adaptatif dans GitBook.

1. Créez un backend personnalisé pour authentifier vos utilisateurs

Afin de commencer à authentifier les utilisateurs avant qu'ils ne puissent consulter votre documentation, vous devrez mettre en place un serveur capable de gérer la connexion et l'authentification des utilisateurs.

Votre backend doit :

Inviter les utilisateurs à se connecter en utilisant votre méthode d'authentification préférée.
Valider les identifiants des utilisateurs et les authentifier.
Générer et signer un JSON Web Token (JWT) après une authentification réussie.
Rediriger les utilisateurs vers GitBook avec le JWT inclus dans l'URL.

2. Signez et transmettez un jeton JWT à GitBook

Une fois que votre backend a authentifié un utilisateur, il doit générer un JWT et le transmettre à GitBook lors de la redirection vers votre site. Le jeton doit être signé à l'aide de la clé privée fournie dans les paramètres d'audience de votre site après avoir activé l'accès authentifié.

L'exemple suivant montre à quoi pourrait ressembler un gestionnaire de requête de connexion dans votre backend personnalisé :

index.ts

import { Request, Response } from 'express';
import * as jose from 'jose';

import { getUserInfo } from '../services/user-info-service';
import { getFeatureFlags } from '../services/feature-flags-service';

const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY!;
const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/myspace';

export async function handleAppLoginRequest(req: Request, res: Response) {
    // Votre logique métier pour gérer la demande de connexion
    // Par exemple, vérifier les identifiants et authentifier l'utilisateur
    //
    // ex. :
    // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
    
    // Générer un JWT signé
    const gitbookVisitorJWT = await new jose.SignJWT({})
        .setProtectedHeader({ alg: 'HS256' })
        .setIssuedAt()
        .setExpirationTime('2h') // Expiration arbitraire de 2 heures
        .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
    
    // Rediriger l'utilisateur vers GitBook avec le jeton JWT dans l'URL
    const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
    res.redirect(redirectURL);
}

3. Configurez une URL de secours

L'URL de secours est utilisée lorsqu'un visiteur non authentifié tente d'accéder à votre site protégé. GitBook le redirigera alors vers cette URL.

Cette URL doit pointer vers un gestionnaire dans votre backend personnalisé, où vous pouvez inviter l'utilisateur à se connecter, l'authentifier puis le rediriger vers votre site avec le JWT inclus dans l'URL.

Par exemple, si votre écran de connexion se trouve à https://example.com/login, vous devez inclure cette valeur comme URL de secours.

Vous pouvez configurer cette URL de secours dans les paramètres d'audience de votre site sous l'onglet "Accès authentifié".

A GitBook screenshot showing where to configure a fallback URL

Lors de la redirection vers l'URL de secours, GitBook inclut un paramètre de requête location à l'URL de secours que vous pouvez utiliser dans votre gestionnaire pour rediriger l'utilisateur vers l'emplacement d'origine de l'utilisateur :

const gitbookVisitorJWT = await new jose.SignJWT({})
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h') // Expiration arbitraire de 2 heures
    .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
    
// Rediriger vers l'URL d'origine de la documentation GitBook avec le JWT inclus comme paramètre de requête jwt_token
// Si un emplacement est fourni, l'utilisateur sera redirigé vers sa destination d'origine
const redirectURL = `${GITBOOK_DOCS_URL}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);

Parce que GitBook s'appuie sur le paramètre de recherche location - vous ne pouvez pas l'utiliser dans votre URL de secours. Par exemple, https://auth.gitbook.com/?location=something n'est pas une URL de secours valide.

4. Configurez un accès authentifié multi-locataires (optionnel)

Si vous utilisez GitBook comme plateforme pour fournir du contenu à vos différents clients, vous aurez probablement besoin de configurer un accès authentifié multi-locataires. Votre backend d'authentification doit être responsable de la gestion de l'authentification sur plusieurs sites différents. Cela est possible dans GitBook avec quelques petites modifications de votre code d'authentification personnalisé.

Ajouter tous les locataires à votre serveur d'authentification

Votre backend d'authentification devra connaître les clés de signature JWT et les URL de tous les sites GitBook que vous souhaitez gérer. Si vous avez deux sites dans votre organisation pour le Client A et le Client B, vous pouvez imaginer que votre code d'authentification stocke une telle correspondance :

const CUSTOMER_A = {
  jwtSigningKey: 'aaa-aaa-aaa-aaa',
  url: 'https://mycompany.gitbook.io/customer-a'
};

const CUSTOMER_B = {
  jwtSigningKey: 'bbb-bbb-bbb-bbb',
  url: 'https://mycompany.gitbook.io/customer-b'
};

Donner un contexte supplémentaire à votre serveur d'authentification

Lorsque GitBook ne parvient pas à authentifier la requête d'un utilisateur, il le redirige vers l'URL de secours. Cette URL pointe vers votre backend d'authentification, qui est responsable d'authentifier l'utilisateur et de le rediriger vers le contenu demandé.

Pour prendre en charge plusieurs locataires, votre backend d'authentification doit savoir à quel site GitBook l'utilisateur est censé accéder. Cette information peut être transmise dans l'URL de secours.

Par exemple, vous pouvez configurer les URLs de secours pour chaque site comme suit :

Site GitBook

URL de secours

Site du client A

https://auth-backend.acme.org/login?site=customer-a

Site du client B

https://auth-backend.acme.org/login?site=customer-b

Votre backend d'authentification peut alors vérifier cette information et gérer la redirection vers le bon site en conséquence :

const customerInfo = req.query.site === 'customer-a' ? CUSTOMER_A : CUSTOMER_B;
  
const gitbookVisitorJWT = await new jose.SignJWT({})
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h') // Expiration arbitraire de 2 heures
    .sign(new TextEncoder().encode(customerInfo.jwtSigningKey));
    
// Redirigez vers l'URL d'origine de la documentation GitBook avec le JWT inclus comme paramètre de requête jwt_token
// Si une localisation est fournie, l'utilisateur sera redirigé vers sa destination d'origine
const redirectURL = `${customerInfo.url}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);

5. Configurez votre backend pour le contenu adaptatif (optionnel)

This feature is still under development and coming soon to the Ultimate site plan.

Please sign up for the waitlist at https://www.gitbook.com/#alpha-waitlist

Pour exploiter la capacité de Contenu Adaptatif dans votre configuration d'accès authentifié, vous pouvez inclure des attributs utilisateur supplémentaires (claims) dans la charge utile du JWT généré par votre backend personnalisé et les inclure dans l'URL lors de la redirection de l'utilisateur vers le site.

Ces claims, lorsqu'ils sont inclus dans le JWT, sont utilisés par GitBook pour adapter le contenu dynamiquement pour les visiteurs de votre site.

En rassemblant tout, l'exemple de code suivant montre comment vous pouvez inclure ces claims dans le JWT, qui peuvent ensuite être utilisés par GitBook pour adapter le contenu pour vos visiteurs :

index.ts

import { Request, Response } from 'express';
import * as jose from 'jose';

import { getUserInfo } from '../services/user-info-service';
import { getFeatureFlags } from '../services/feature-flags-service';

const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY!;
const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/myspace';

export async function handleAppLoginRequest(req: Request, res: Response) {
    // Votre logique métier pour gérer la demande de connexion
    // Par exemple, vérifier les identifiants et authentifier l'utilisateur
    //
    // ex. :
    // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
    
    // Pour cet exemple, supposons un objet utilisateur connecté
    const loggedInUser = { id: '12345' }; // Remplacez par la logique d'authentification réelle

    // Récupérer les informations utilisateur à transmettre à GitBook
    const userInfo = await getUserInfo(loggedInUser.id);
    
    // Générer un JWT signé et inclure les attributs utilisateur comme claims
    const gitbookVisitorClaims = {
        firstName: userInfo.firstName,
        lastName: userInfo.lastName,
        isBetaUser: userInfo.isBetaUser,
        products: userInfo.products.map((product) => product.name),
        featureFlags: await getFeatureFlags({ userId: loggedInUser.id })
    };
    
    const gitbookVisitorJWT = await new jose.SignJWT(gitbookVisitorClaims)
        .setProtectedHeader({ alg: 'HS256' })
        .setIssuedAt()
        .setExpirationTime('2h') // Expiration arbitraire de 2 heures
        .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
    
    // Redirigez l'utilisateur vers GitBook avec le token JWT dans l'URL
    const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
    res.redirect(redirectURL);
}

Après avoir configuré et paramétré les bons claims à envoyer à GitBook, rendez-vous sur « Adapter votre contenu » pour continuer la configuration de votre site.

Mis à jour il y a 1 mois

Ce contenu vous a-t-il été utile ?