📍 Article principal : BookStack 2026 : guide pratique.

BookStack supporte OIDC depuis 24.05. Brancher sur Authentik unifie les logins de votre stack auto-hébergée.

Prérequis

BookStack v24.05+ en production.
Authentik en production.
Niveau : avancé.
Temps : 30-45 min.

Avant de configurer le SSO, vérifiez les prérequis suivants. Authentik 2025.10 ou plus récent installé et accessible via HTTPS valide (certificat Let’s Encrypt fonctionnel). BookStack 24.10 ou plus récent, configuré avec une base de données dédiée. Les deux services accessibles depuis le réseau interne ou via reverse proxy. Un compte administrateur dans Authentik et dans BookStack. Pour un déploiement à Plateau ou Almadies sur deux VPS Hetzner, comptez 30-45 minutes d’installation initiale avant cette phase OIDC.

Étape 1 — Provider OIDC Authentik

Authentik admin → Providers → Create → OAuth2/OpenID :

Name: bookstack-provider
Authentication flow: default-authentication-flow
Authorization flow: default-provider-authorization-explicit-consent
Client type: confidential
Redirect URIs: https://docs.votre-entreprise.com/oidc/callback
Scopes: openid email profile
Subject mode: based on user's email

Note client_id et client_secret.

Connectez-vous à l’admin Authentik. Naviguez vers Applications puis Providers puis Create. Sélectionnez OAuth2/OpenID Provider. Donnez le nom ‘BookStack OIDC’. Choisissez le client_type Confidential. Authentik génère automatiquement client_id et client_secret — copiez-les dans un fichier .env temporaire car le secret n’est affichable qu’une seule fois. Définissez les redirect URIs sur l’URL de votre BookStack avec le suffixe /oidc/callback. Choisissez le signing key par défaut (généralement authentik Self-signed Certificate).

Étape 2 — Application Authentik

Name: BookStack
Slug: bookstack
Provider: bookstack-provider
Launch URL: https://docs.votre-entreprise.com

Toujours dans Authentik, allez dans Applications puis Applications puis Create. Le slug doit être bookstack et pointer vers le provider créé à l’étape 1. Le launch URL est l’URL publique de votre BookStack. L’icône peut être l’icône officielle BookStack téléchargée depuis bookstackapp.com. Restreignez l’accès via Policy Bindings : par défaut tous les utilisateurs Authentik authentifiés peuvent se connecter, mais vous pouvez limiter à un groupe spécifique (par exemple bookstack-users).

Étape 3 — Variables BookStack

Coolify → BookStack → Environment :

AUTH_METHOD=oidc
OIDC_NAME=Authentik
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=client_id-copié
OIDC_CLIENT_SECRET=secret-copié
OIDC_ISSUER=https://auth.votre-entreprise.com/application/o/bookstack/
OIDC_ISSUER_DISCOVER=true
OIDC_USER_TO_GROUPS=true
OIDC_GROUPS_CLAIM=groups

Modifiez le fichier .env de BookStack avec les variables OIDC suivantes. AUTH_METHOD=oidc qui active la méthode OpenID Connect. OIDC_NAME=’Authentik’ qui est le label affiché sur le bouton de login. OIDC_CLIENT_ID et OIDC_CLIENT_SECRET avec les valeurs récupérées à l’étape 1. OIDC_ISSUER avec l’URL https://authentik.example.com/application/o/bookstack/ (le slug doit correspondre). OIDC_AUTO_REGISTER=true pour créer automatiquement les comptes BookStack à la première connexion.

Étape 4 — Restart container

Coolify → Redeploy.

Pour que BookStack lise les nouvelles variables d’environnement, redémarrez le container. Avec Docker Compose, lancez docker compose restart bookstack dans le répertoire du fichier compose.yaml. Avec Coolify, cliquez sur Redeploy dans l’interface du service. Le redémarrage prend 15-30 secondes. Vérifiez les logs avec docker compose logs -f bookstack pour confirmer l’absence d’erreurs OIDC au démarrage.

Étape 5 — Test login

Mode incognito → docs.votre-entreprise.com → bouton « Sign in with Authentik ».

Redirection auth → login + MFA → consent → retour BookStack connecté.

Ouvrez l’URL publique de BookStack en navigation privée. Le formulaire de connexion doit afficher un bouton supplémentaire ‘Authentik’ à côté de la connexion email/password locale. Cliquez dessus, vous êtes redirigé vers Authentik pour vous authentifier. Après validation, vous revenez sur BookStack connecté avec le compte créé automatiquement. Si une erreur ‘Invalid issuer’ apparaît, vérifiez que OIDC_ISSUER correspond exactement (avec ou sans slash final selon votre version Authentik).

Étape 6 — Mapping groupes Authentik → roles BookStack

Authentik → Property Mapping → ajouter mapping groups → claim groups.

BookStack admin → Roles → assignment auto par groupe Authentik.

Pour donner automatiquement les bonnes permissions BookStack selon les groupes Authentik, ajoutez OIDC_GROUPS_CLAIM=groups au .env BookStack. Dans Authentik, créez les groupes bookstack-admin, bookstack-editor, bookstack-viewer. Configurez le mapping dans BookStack via Settings puis Roles puis Edit role : décochez ‘Disable external assignment’ et inscrivez le nom du groupe Authentik correspondant. À la prochaine connexion, l’utilisateur reçoit le rôle correspondant à son groupe Authentik.

Étape 7 — Désactiver login local

AUTH_METHOD=oidc  # Force OIDC, supprime login email/password

Une fois le SSO confirmé fonctionnel, désactivez la connexion email/password locale pour éviter le contournement du SSO. Ajoutez AUTH_METHOD=oidc au .env (déjà fait à l’étape 3) et AUTH_AUTO_INITIATE=true qui redirige automatiquement vers Authentik sans afficher le formulaire local. Conservez un compte admin local de secours en cas de panne Authentik. Ce compte de secours s’utilise via l’URL /login?force_local=1 si elle est activée.

Étape 8 — Auto-création utilisateurs

BookStack crée auto compte au premier login OIDC. Email match Authentik = compte associé.

Avec OIDC_AUTO_REGISTER=true, BookStack crée automatiquement un compte local lorsqu’un utilisateur Authentik se connecte pour la première fois. L’email et le nom sont récupérés depuis les claims OIDC. Pour contrôler quels utilisateurs peuvent créer des comptes, restreignez l’accès dans Authentik au niveau de l’Application Policy. Par défaut, BookStack assigne le rôle Viewer aux nouveaux comptes. Pour assigner un autre rôle par défaut, paramétrez OIDC_USER_TO_GROUPS=true et configurez le groupe par défaut dans Authentik.

Étape 9 — Logout SSO

Variable OIDC_END_SESSION_ENDPOINT pour logout cascade vers Authentik.

Le logout BookStack ne déconnecte pas Authentik par défaut. Pour un logout SSO complet (utilisateur déconnecté de tous les services), ajoutez OIDC_END_SESSION_ENDPOINT au .env de BookStack avec l’URL https://authentik.example.com/application/o/bookstack/end-session/. À la déconnexion, BookStack appelle cet endpoint qui invalide la session Authentik. Sans cette configuration, l’utilisateur reste connecté à Authentik et peut se reconnecter à BookStack sans authentification.

Étape 10 — Audit logs

BookStack logs login OIDC. Settings → Audit Log. Ingestion Loki via volume.

Authentik enregistre tous les événements de connexion dans Events puis Logs accessible depuis l’admin. Filtrez par action login pour voir les tentatives sur BookStack. Pour la conformité ou l’audit interne, exportez régulièrement ces logs via l’API Authentik. BookStack maintient son propre journal d’audit dans Settings puis Audit Log qui trace les actions de modification de contenu. La combinaison des deux donne une traçabilité complète : qui s’est connecté quand, et quelles modifications il a fait.

Erreurs fréquentes

Erreur	Cause	Solution
« Invalid redirect_uri »	URL exacte mismatch	Vérifier callback Authentik exact
Compte créé sans email	Scope email manquant	Add scope email
Groupes pas mappés	OIDC_GROUPS_CLAIM	Property Mapping Authentik
Logout pas cascade	END_SESSION_ENDPOINT manquant	Configurer URL exact
Boucle redirect	Cookie domain	Vérifier base domain
Discovery URL 404	Slug app différent	Vérifier slug Authentik

Ce que les retours d’expérience locaux ajoutent

Trois précisions. Multi-tenant ESN : un Authentik tenant client + un BookStack par client. Audit conformité : logs Authentik + BookStack ingérés Loki = trace complète. Suppression employé : retirer du groupe Authentik = accès BookStack coupé.

Plusieurs équipes africaines qui ont déployé cette stack à Dakar, Cotonou et Bamako rapportent trois écueils récurrents. Premièrement, le certificat Let’s Encrypt expire silencieusement si renew.timer systemd n’est pas activé : prévoyez un monitoring Uptime Kuma sur le port 443. Deuxièmement, un mauvais paramétrage du redirect_uri génère des boucles infinies de redirection — copiez-collez exactement la valeur en respectant le slash final. Troisièmement, BookStack 24.10 a changé le format des claims, vérifiez que vous tournez sur la dernière version mineure.

Tutoriels frères

Cette intégration s’inscrit dans un parcours plus large pour bâtir une stack collaborative self-hostée. Configurer Outline avec Authentik OIDC suit le même pattern et permet d’unifier la documentation interne. Migrer Mattermost vers Authentik SSO consolide la messagerie d’équipe. Pour les sites publics, Authentik peut aussi protéger un WordPress via le plugin OpenID Connect Generic. Cette cohérence d’identité réduit les frictions et la dette de gestion des comptes éparpillés.

FAQ

SAML supporté ? Oui. AUTH_METHOD=saml2. Configuration séparée.

Multi-IdP ? BookStack supporte un OIDC à la fois.

Group sync ? Oui via OIDC_USER_TO_GROUPS=true.

Tester sans casser prod ? Staging Authentik + staging BookStack avant bascule.

Migration login local → SSO ? Comptes locaux conservés. Premier login OIDC associe par email.

Pour explorer plus loin

🔝 guide général : guide pratique BookStack 2026

Une fois le SSO Bookstack-Authentik en place, étendez la couverture à vos autres outils internes. Authentik supporte SAML, OAuth2, LDAP en plus d’OIDC, ce qui couvre 95 % des applications modernes. Pour les outils legacy, le proxy provider d’Authentik agit comme reverse proxy d’authentification, ajoutant une couche SSO sans modifier l’application. La documentation officielle goauthentik.io maintient une liste à jour des intégrations testées. Pour la sauvegarde stratégique de la stack, voyez nos guides Restic et Litestream.

Pourquoi connecter Bookstack à Authentik via OIDC

Bookstack est un wiki self-hosted élégant, particulièrement adapté à la documentation technique d’une équipe ouest-africaine de cinq à cinquante personnes. Couplé à Authentik comme fournisseur d’identité OIDC, vous obtenez un Single Sign-On centralisé : un employé qui rejoint une équipe à Dakar ou Abidjan obtient instantanément l’accès aux wikis, dashboards et outils internes via un seul mot de passe et une seule session. Quand il quitte, un seul clic dans Authentik révoque tous les accès. Ce tutoriel installe Bookstack derrière Authentik en moins d’une heure.

Prérequis : Authentik 2024.x ou 2025.x déjà déployé et accessible sur https://auth.exemple.io, Bookstack v24+ installé via Docker sur le même VPS ou un VPS distinct, accès admin aux deux.

Étape 1 — Créer un Provider OAuth2/OIDC dans Authentik

Connectez-vous à l’admin Authentik. Allez dans Applications → Providers → Create. Choisissez le type OAuth2/OpenID Provider. Nommez-le bookstack-oidc. Authorization flow : default-provider-authorization-implicit-consent (ou explicit-consent selon votre politique). Notez le Client ID et le Client Secret générés ; ils seront copiés côté Bookstack. Dans Redirect URIs, ajoutez l’URL de callback Bookstack : https://wiki.exemple.io/oidc/callback.

Étape 2 — Configurer les scopes et les claims

Bookstack attend les claims standard openid, email, profile. Dans le Provider Authentik, sélectionnez les scopes correspondants dans la section Scopes. Pour mapper les groupes Authentik vers les rôles Bookstack, ajoutez un Property Mapping personnalisé qui expose le claim groups dans le token : Customization → Property Mappings → Create → Scope Mapping, Scope name groups, expression Python return [group.name for group in user.ak_groups.all()]. Référencez ce mapping dans le Provider.

Étape 3 — Créer une Application dans Authentik

Toujours côté Authentik, allez dans Applications → Applications → Create. Nommez Bookstack, slug bookstack, Provider bookstack-oidc. L’icône optionnelle (logo Bookstack) améliore l’UX du portail Authentik. Définissez les politiques d’accès : par exemple, exiger l’appartenance au groupe wiki-users. Toute personne hors de ce groupe verra une erreur 403 lors de la tentative de login.

Étape 4 — Récupérer les endpoints OIDC d’Authentik

Dans la vue du Provider créé, copiez les URLs : Authorize URL (https://auth.exemple.io/application/o/authorize/), Token URL (https://auth.exemple.io/application/o/token/), Userinfo URL (https://auth.exemple.io/application/o/userinfo/), Issuer URL (https://auth.exemple.io/application/o/bookstack/). Ces quatre URLs alimentent la configuration Bookstack.

Authentik expose tous ses endpoints OIDC via le document de découverte standard. Ouvrez https://authentik.example.com/application/o/bookstack/.well-known/openid-configuration dans le navigateur. Vous obtenez un JSON avec les URLs authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint, jwks_uri. Ces endpoints sont automatiquement détectés par BookStack via OIDC_ISSUER, vous n’avez généralement pas à les configurer manuellement. La présence de ce document de découverte confirme que le provider Authentik est correctement publié.

Étape 5 — Configurer Bookstack pour utiliser OIDC

Bookstack supporte OIDC nativement depuis la version v22. Éditez le fichier .env de Bookstack (ou la section environment du docker-compose.yml) :

AUTH_METHOD=oidc
OIDC_NAME=Authentik
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=votre-client-id
OIDC_CLIENT_SECRET=votre-client-secret
OIDC_ISSUER=https://auth.exemple.io/application/o/bookstack/
OIDC_ISSUER_DISCOVER=true
OIDC_USER_TO_GROUPS=true
OIDC_GROUPS_CLAIM=groups
OIDC_REMOVE_FROM_GROUPS=false

Le mode OIDC_ISSUER_DISCOVER=true évite de saisir manuellement les quatre URLs : Bookstack interroge l’endpoint /.well-known/openid-configuration d’Authentik et récupère tout automatiquement. Cette approche résiste aux changements de version Authentik.

Étape 6 — Redémarrer Bookstack et tester

Relancez le conteneur : docker compose up -d --force-recreate bookstack. La page de login Bookstack affiche désormais un bouton Login with Authentik. Cliquez ; vous êtes redirigé vers Authentik pour authentification, puis ramené à Bookstack connecté. Si une erreur survient, consultez les logs : docker compose logs -f bookstack et la section Events d’Authentik. Les problèmes les plus fréquents : Redirect URI mal configuré, claim groups absent du token, Issuer URL avec ou sans slash final.

Étape 7 — Mapper les groupes Authentik vers les rôles Bookstack

Dans Bookstack admin → Settings → Users → Roles, créez les rôles correspondant à vos groupes Authentik : wiki-admin, wiki-editor, wiki-viewer. Le nom du rôle Bookstack doit matcher exactement le nom du groupe Authentik passé dans le claim groups. À chaque connexion, Bookstack synchronise automatiquement l’appartenance aux rôles depuis le token. Un utilisateur retiré du groupe wiki-editor côté Authentik perd ses droits d’édition à sa prochaine reconnexion.

Étape 8 — Désactiver l’authentification locale

Une fois OIDC validé, retirez la possibilité de créer des comptes locaux. Dans .env Bookstack : AUTH_METHOD=oidc uniquement (sans fallback). Désactivez aussi l’enregistrement public : AUTH_AUTO_INITIATE=true redirige automatiquement la page de login vers Authentik sans afficher de formulaire. Cette mesure évite la coexistence dangereuse de comptes locaux orphelins après une migration.

Étape 9 — Sécuriser le secret OIDC

Le Client Secret OIDC est aussi sensible qu’un mot de passe master. Stockez-le dans un gestionnaire de secrets (Bitwarden organisation, HashiCorp Vault, ou simple .env protégé par chmod 600). Ne le committez jamais dans Git ; ajoutez .env au .gitignore. Pour faire tourner ce secret régulièrement, régénérez-le côté Authentik tous les six mois et mettez à jour Bookstack en conséquence. Lectures complémentaires sur la sécurité serveur, consultez notre checklist sécurité Linux et notre guide monitoring Uptime Kuma.

Étape 10 — Sauvegarder Authentik et Bookstack ensemble

Une perte d’Authentik invalide tous les SSO. Sauvegardez quotidiennement la base PostgreSQL d’Authentik et le volume de données de Bookstack (uploads, attachments). Testez la restauration sur un VPS de staging tous les trimestres. Une procédure de restauration jamais testée n’existe pas.

Une stack SSO sans backup est une bombe à retardement : si Authentik tombe, plus personne ne peut se connecter à BookStack. Sauvegardez les deux ensemble avec Restic ou Borg, en incluant la base PostgreSQL d’Authentik et le volume MySQL de BookStack. Stockez les backups sur un stockage S3 distinct (Backblaze B2, MinIO self-hosted) avec rétention 30 jours. Testez la restauration trimestriellement : restaurez Authentik avant BookStack, sinon les utilisateurs ne peuvent pas se reconnecter.

Étape 11 — Activer la 2FA via Authentik

Centraliser l’authentification dans Authentik permet d’imposer la 2FA une seule fois pour tous les outils branchés derrière. Dans Authentik, allez dans Flows → default-authentication-flow → ajoutez un Stage Authenticator Validation. Configurez-le pour exiger TOTP (Google Authenticator, Aegis, Bitwarden Authenticator) ou WebAuthn (clés YubiKey). Une fois activé, chaque utilisateur doit enrôler un second facteur lors de sa prochaine connexion. Bookstack hérite automatiquement de cette protection sans ligne de configuration supplémentaire — c’est précisément la valeur d’un IdP centralisé.

Étape 12 — Configurer un timeout de session adapté

Un wiki contenant de la documentation sensible (procédures internes, secrets d’API rédigés à tort, schémas d’architecture) ne devrait pas garder une session ouverte indéfiniment. Côté Authentik, dans le Provider OAuth2, ajustez Access code validity à 1 heure et Token validity à 8 heures. Côté Bookstack, ajustez SESSION_LIFETIME à 480 minutes dans le .env. Ce calibrage couvre une journée de travail sans demander de relogin permanent, tout en limitant la fenêtre d’exploitation d’un poste laissé sans surveillance dans un open space partagé.

Étape 13 — Logs d’audit côté Authentik

Authentik loge chaque tentative d’authentification dans Events → Logs avec horodatage, IP source, navigateur et résultat. Conservez ces logs au moins six mois ; ils servent de preuve en cas d’enquête après un incident. Pour un export structuré, configurez l’envoi vers un puits de logs externe (Loki, Elasticsearch, SIEM Wazuh) via la section Outposts → Event Forwarder. Une recherche par utilisateur et plage de dates permet de reconstituer rapidement le parcours d’un compte suspecté de compromission.

Étape 14 — Provisionnement automatique avec SCIM ou LDAP

Pour une entreprise qui possède déjà un annuaire LDAP (Active Directory, OpenLDAP, Samba 4), Authentik peut synchroniser les utilisateurs et groupes en lecture depuis cet annuaire. Allez dans Directory → Federation & Social login → Create LDAP source. Indiquez le serveur, le bind DN, le mot de passe, la base de recherche. Les utilisateurs LDAP apparaissent dans Authentik et peuvent se connecter à Bookstack via leur identifiant d’entreprise habituel. Les groupes LDAP sont aussi synchronisés et propagés vers Bookstack via le claim groups, ce qui automatise totalement la gestion des accès au wiki sans double saisie.

Étape 15 — Tester la déconnexion globale

Le SSO impose aussi un Single Logout fiable. Testez la séquence : déconnectez-vous depuis Bookstack ; la session Authentik doit-elle aussi se terminer ? Cela dépend de la directive OIDC_END_SESSION_ENDPOINT et du paramètre id_token_hint envoyé. Configurez Bookstack pour rediriger vers https://auth.exemple.io/application/o/bookstack/end-session/ à la déconnexion. Sans cette redirection, l’utilisateur reste authentifié dans Authentik et peut être reloggé sur Bookstack sans saisir d’identifiants — failure-mode discret mais dangereux sur un poste partagé.

Étape 16 — Personnaliser la page de login Authentik aux couleurs de l’entreprise

L’expérience utilisateur compte. Une page de login générique avec le logo Authentik par défaut donne l’impression d’un service tiers, ce qui peut inquiéter un employé peu technique basé à Lomé ou Cotonou qui se demande s’il s’agit bien du portail interne. Dans Authentik, allez dans System → Tenants → default. Personnalisez le logo, le favicon, la palette de couleurs CSS, et les libellés français. Une page de login aux couleurs de l’entreprise rassure et professionnalise immédiatement l’expérience SSO.

Étape 17 — Documenter la procédure d’onboarding et d’offboarding

Avec un IdP centralisé, l’onboarding d’un nouvel employé tient en trois actions : créer le compte dans Authentik, ajouter aux groupes adéquats (wiki-editor, monitoring-viewer, etc.), envoyer le lien d’enrôlement 2FA. L’offboarding est encore plus simple : un seul clic sur Disable User dans Authentik invalide instantanément l’accès à Bookstack et tous les autres services SSO. Documentez ces deux procédures dans Bookstack lui-même, dans un livre Procédures internes protégé en lecture aux seuls membres RH et IT. Cette boucle réflexive — Bookstack documente comment provisionner Bookstack — illustre la maturité du dispositif.

Étape 18 — Surveiller la santé d’Authentik en continu

Si Authentik tombe, Bookstack devient inaccessible. Ajoutez un monitor Uptime Kuma de type HTTP(s) sur l’endpoint /.well-known/openid-configuration d’Authentik. Toute panne de l’IdP déclenche immédiatement une alerte Telegram qui permet d’intervenir avant que l’équipe ne se rende compte du blocage. Pour les organisations critiques, déployez un second Authentik en standby avec réplication PostgreSQL ; un basculement DNS en cas d’incident majeur restaure le SSO en moins de cinq minutes.

Étape 19 — Étendre le SSO aux autres outils internes

Une fois Bookstack connecté, généralisez. Authentik supporte OIDC, SAML et proxy applicatif pour des outils sans SSO natif. Connectez Grafana, Nextcloud, Gitea, Vaultwarden, Portainer, Mattermost. Chaque nouvel outil ajouté décuple la valeur de l’IdP centralisé : l’employé n’a plus qu’un seul mot de passe à mémoriser et à protéger, l’équipe IT n’a plus qu’un seul endroit où révoquer les accès. Cette consolidation est l’un des leviers les plus puissants pour professionnaliser une équipe technique de PME ouest-africaine sans budget cloud Microsoft 365 ou Google Workspace Enterprise.

Étape 20 — Évaluer le coût total d’exploitation

Authentik et Bookstack tournent confortablement sur un seul VPS Hetzner CX22 (2 vCPU, 4 Go RAM) facturé environ 6 EUR par mois soit 3936 FCFA. Comparé à un Okta Workforce Identity à 6 USD par utilisateur par mois, l’économie pour une équipe de vingt personnes dépasse les 100 USD mensuels — soit plus de 65 000 FCFA. Sur un an, cela finance un développeur junior à temps partiel ou plusieurs licences logicielles utiles.