Le SSO Enterprise est devenu gratuit dans la v3
Stirling PDF regroupe plus de 50 opérations PDF — fusion, découpe, compression, conversion de format, OCR, signature, réorganisation de pages — dans une interface web auto-hébergée. Depuis sa création, l'outil a grossi sur GitHub (87 000 étoiles, licence MIT) et s'est imposé comme la référence open source pour le traitement documentaire en équipe.
La v2 compartimentait les fonctions : les opérations de base étaient libres, le SSO OAuth2 et quelques fonctions avancées étaient réservées au plan Enterprise. Ce modèle freemium avait du sens commercial, mais il créait une situation inconfortable pour les équipes auto-hébergées : Stirling PDF accessible sans mot de passe sur un port ouvert, ou avec des comptes locaux impossible à révoquer depuis un annuaire central.
La PR #8137 a fusionné en septembre 2026 et a réorganisé la grille de fonctionnalités. La v3.0.0 (release note : github.com/Stirling-Tools/Stirling-PDF/releases/tag/v3.0.0) a livré ce changement, confirmé stable dans la v3.1.0 (5 octobre 2026). Résultat : SECURITY_OAUTH2_ENABLED=true fonctionne sur n'importe quelle installation ≥ v3.0.0, sans clé de licence, sans plan payant.
Ce que le SSO gratuit change concrètement
- Accès centralisé : tous les membres de l'équipe s'authentifient via votre fournisseur d'identité existant (Authentik, Keycloak, Zitadel, Okta…) — aucun compte local à créer ni à révoquer manuellement.
- Révocation immédiate : désactiver un compte dans votre IdP ferme l'accès à Stirling PDF en même temps qu'au reste de votre stack — pas de comptes orphelins.
- Conformité : les accès sont journalisés côté IdP, pas dans Stirling PDF. Audit trail centralisé, sans configuration supplémentaire.
- Désactivation du formulaire local : une seule variable (
SECURITY_OAUTH2_AUTO_CREATE_USER=falsecombinée à la désactivation du login formulaire) empêche tout contournement. - Support PKCE : la v3 implémente correctement le flux PKCE — les IdP qui l'exigent (Authentik en particulier) fonctionnent sans configuration dérogatoire.
- Mise à jour non destructive : activer le SSO sur une instance existante ne supprime pas les fichiers traités ni l'historique.
Prérequis
Avant de commencer :
Stirling PDF ≥ v3.0.0 déjà déployé. Si votre instance tourne en v2.x, mettez-la à jour (docker compose pull && docker compose up -d) et vérifiez avec docker compose logs stirling-pdf | grep version.
Un fournisseur d'identité OIDC opérationnel. Ce guide couvre les deux IdP les plus répandus en stack auto-hébergée : Authentik (un conteneur dédié, généralement sur le même VPS) et Keycloak (déployé séparément, recommandé pour les environnements multi-applications). Si vous n'avez pas encore d'IdP, le guide Héberger Authentik sur un VPS couvre l'installation complète.
Un reverse proxy avec TLS actif. Stirling PDF doit être servi en HTTPS — les cookies de session OAuth2 sont Secure par défaut. nginx, Caddy et Traefik fonctionnent tous sans modification.
Ressources : 1 vCPU / 2 Go RAM minimum. L'OCR et la conversion de PDF complexes sont gourmands — prévoir 2 vCPU / 4 Go pour un usage en équipe au-dessus de 5 utilisateurs simultanés.
Activer le SSO dans Stirling PDF
Mettre à jour vers v3.0.0 ou supérieur
Si votre
docker-compose.ymlpointe encore sur l'imagefrooodle/s-pdf:latestou une version figée ≤ 2.x, mettez d'abord l'image à jour :docker compose pull stirling-pdf docker compose up -d stirling-pdf docker compose logs stirling-pdf --tail=20Vérifiez que la ligne
Stirling-PDF versionaffiche3.0.0ou supérieur avant de continuer.Ajouter les variables OAuth2 dans settings.yml
Stirling PDF charge sa configuration depuis
./configs/settings.yml(chemin du volume monté dans le compose). Ouvrez ce fichier et ajoutez ou complétez le blocsecurity:security: enableLogin: true oauth2: enabled: true provider: oidc issuer: https://authentik.votre-domaine.com/application/o/stirling-pdf/ clientId: VOTRE_CLIENT_ID clientSecret: VOTRE_CLIENT_SECRET scopes: openid,profile,email useAsUsername: email autoCreateUser: trueLes six variables sont obligatoires.
SECURITY_OAUTH2_USE_AS_USERNAMEdétermine quel champ du token OIDC sert de nom d'utilisateur dans Stirling PDF —emailest le choix habituel,preferred_usernamefonctionne aussi si votre IdP le fournit.Alternativement, ces variables peuvent être passées directement dans le
docker-compose.ymlsousenvironment:avec le préfixeSECURITY_OAUTH2_:environment: SECURITY_OAUTH2_ENABLED: "true" SECURITY_OAUTH2_PROVIDER: oidc SECURITY_OAUTH2_ISSUER: https://authentik.votre-domaine.com/application/o/stirling-pdf/ SECURITY_OAUTH2_CLIENT_ID: VOTRE_CLIENT_ID SECURITY_OAUTH2_CLIENT_SECRET: VOTRE_CLIENT_SECRET SECURITY_OAUTH2_SCOPES: openid,profile,email SECURITY_OAUTH2_USE_AS_USERNAME: email SECURITY_OAUTH2_AUTO_CREATE_USER: "true"Redémarrer le conteneur et vérifier les logs
Appliquez la configuration :
docker compose restart stirling-pdf docker compose logs stirling-pdf --follow --tail=30Cherchez la ligne
OAuth2 SSO enableddans les logs de démarrage. Si vous voyezError loading OAuth2 issuer metadata, le point de découverte OIDC (/.well-known/openid-configuration) est inaccessible depuis le conteneur — vérifiez que l'URL deissuerest joignable en réseau Docker.Testez ensuite que l'endpoint de redirection existe :
curl -I https://pdf.votre-domaine.com/oauth2/authorization/oidcRéponse attendue :
HTTP/2 302vers l'URL d'autorisation de votre IdP. Un404signifie que le SSO n'est pas activé (variable mal lue ou container non redémarré).
Configurer Authentik comme fournisseur d'identité
Dans l'interface d'administration Authentik (https://authentik.votre-domaine.com/if/admin/) :
1. Créer un Provider OAuth2/OIDC
Allez dans Applications → Providers → Create. Choisissez OAuth2/OpenID Connect Provider. Donnez-lui un nom (par exemple stirling-pdf-provider). Dans le champ Redirect URIs, entrez exactement :
https://pdf.votre-domaine.com/login/oauth2/code/oidcActivez PKCE (Proof Key for Code Exchange) si la case est disponible — Authentik l'exige par défaut depuis la version 2024.x. Laissez les scopes sur openid, profile, email.
Notez le Client ID et le Client Secret générés — ce sont les valeurs à reporter dans settings.yml.
2. Créer l'Application
Allez dans Applications → Applications → Create. Nommez-la Stirling PDF, sélectionnez le Provider créé à l'étape précédente. Enregistrez.
3. Récupérer l'URL de l'issuer
L'URL de découverte OIDC d'Authentik suit le motif :
https://authentik.votre-domaine.com/application/o/stirling-pdf/Où stirling-pdf est le slug de l'Application (pas du Provider). Vérifiez en ouvrant https://authentik.votre-domaine.com/application/o/stirling-pdf/.well-known/openid-configuration dans un navigateur — vous devez recevoir un JSON valide avec authorization_endpoint.
Configurer Keycloak comme fournisseur d'identité
Dans la console d'administration Keycloak (https://keycloak.votre-domaine.com/admin/) :
1. Sélectionner le Realm
Choisissez le realm qui héberge vos utilisateurs (par exemple master pour un usage interne, ou un realm dédié internal-apps).
2. Créer un Client OIDC
Allez dans Clients → Create client. Renseignez :
- Client ID : stirling-pdf (valeur libre, mais à reporter dans settings.yml)
- Client Protocol : openid-connect
- Access Type : confidential
Dans l'onglet Settings, ajoutez la Redirect URI :
https://pdf.votre-domaine.com/login/oauth2/code/oidcActivez Standard Flow et désactivez Implicit Flow.
3. Récupérer le Client Secret
Onglet Credentials → copiez la valeur de Secret.
4. URL de l'issuer pour Keycloak
L'URL suit le motif :
https://keycloak.votre-domaine.com/realms/VOTRE_REALMVérifiez en ouvrant https://keycloak.votre-domaine.com/realms/VOTRE_REALM/.well-known/openid-configuration.
Durcissement : désactivez le formulaire de connexion local après le SSO
Une fois le SSO validé et tous vos utilisateurs migrés, il est conseillé de désactiver le formulaire de connexion par mot de passe local — qui reste actif par défaut même avec OAuth2 activé. Ajoutez dans settings.yml :
security:
enableLogin: true
loginMethod: oauth2Désactiver loginMethod: oauth2 (et retirer local) empêche tout contournement du SSO via le formulaire. Conservez un compte administrateur d'urgence dans votre IdP avant d'appliquer cette configuration — si votre IdP devient inaccessible, vous ne pourrez plus vous connecter.
Dépannage des erreurs courantes
redirect_uri mismatch — L'URI enregistrée dans le fournisseur ne correspond pas exactement à ce que Stirling PDF envoie. La valeur attendue est https://pdf.votre-domaine.com/login/oauth2/code/oidc, sans slash final, en HTTPS obligatoire. Vérifiez l'absence d'espace ou de caractère invisible dans le champ de votre IdP.
PKCE required ou code_challenge_method unsupported — Authentik exige PKCE par défaut depuis 2024.x. Si votre version de Stirling PDF est < 3.0.0, elle ne supporte pas PKCE — mettez à jour. Sur la v3, le flux PKCE est pris en charge nativement.
Cookies cross-domain perdus après le retour de l'IdP — Si Stirling PDF est servi sur un sous-domaine différent de votre IdP, vérifiez que votre reverse proxy n'injecte pas de SameSite=Strict sur les cookies de session. La valeur correcte est SameSite=Lax. Symptôme : la redirection depuis l'IdP aboutit à une page blanche ou un rechargement en boucle.
Error loading OAuth2 issuer metadata au démarrage — Le conteneur Stirling PDF ne peut pas atteindre le point de découverte de votre IdP. Causes fréquentes : réseau Docker isolé (le conteneur ne peut pas résoudre le nom de domaine de l'IdP), certificat TLS auto-signé non approuvé, ou IdP éteint. Testez depuis le conteneur : docker compose exec stirling-pdf curl -s https://authentik.votre-domaine.com/application/o/stirling-pdf/.well-known/openid-configuration.
L'utilisateur se connecte mais voit une erreur 403 Forbidden — SECURITY_OAUTH2_AUTO_CREATE_USER est à false (valeur par défaut) et l'utilisateur n'existe pas encore dans Stirling PDF. Passez-le à true le temps que les comptes se créent à la première connexion, ou créez les utilisateurs manuellement depuis l'interface d'administration de Stirling PDF.
SSO sans surcoût, un bloc à la fois
Le SSO n'est plus un argument de vente d'une édition payante — c'est une configuration de trois blocs dans un fichier YAML. La v3.0.0 a rendu ce changement définitif, et la v3.1.0 (5 octobre 2026) confirme la stabilité du nouveau comportement.
Si votre instance Stirling PDF est exposée à votre équipe sans authentification centralisée aujourd'hui, la correction tient en une mise à jour du conteneur, trois variables d'environnement, et deux écrans de configuration dans votre IdP. Le retour : révocation instantanée, audit trail centralisé, et un vecteur d'accès non contrôlé fermé.
Un point mérite d'être souligné sur le déclencheur de la migration : le passage à la v3 ne nécessite pas de réinstaller Stirling PDF depuis zéro. Les volumes Docker existants — fichiers traités, configuration — sont préservés. La seule étape obligatoire avant d'activer le SSO est de vérifier que l'image tourne bien en v3.0.0 ou supérieur, puis d'ajouter les variables dans le fichier de configuration. L'ensemble de la procédure est réversible : retirer les variables SECURITY_OAUTH2_* et redémarrer le conteneur désactive le SSO sans effet de bord.
Pour aller plus loin sur les IdP open source couverts ici, les guides Héberger Authentik sur un VPS et Authentik, Authelia ou Keycloak : choisir son SSO couvrent le déploiement et les arbitrages de chaque solution.
