Enterprise SSO became free in v3
Stirling PDF packages over 50 PDF operations — merge, split, compress, convert, OCR, sign, reorder pages — into a self-hosted web interface. Since its launch, the tool has grown on GitHub (87,000 stars, MIT license) and established itself as the open source reference for team document processing.
v2 compartmentalized features: basic operations were free, OAuth2 SSO and a few advanced functions were reserved for the Enterprise plan. This freemium model made commercial sense, but it created an uncomfortable situation for self-hosted teams: Stirling PDF reachable without a password on an open port, or with local accounts impossible to revoke from a central directory.
PR #8137 merged in September 2026 and reorganized the feature grid. v3.0.0 (release notes: github.com/Stirling-Tools/Stirling-PDF/releases/tag/v3.0.0) shipped this change, confirmed stable in v3.1.0 (October 5, 2026). Result: SECURITY_OAUTH2_ENABLED=true works on any installation ≥ v3.0.0, without a license key, without a paid plan.
What free SSO changes in practice
- Centralized access: all team members authenticate through your existing identity provider (Authentik, Keycloak, Zitadel, Okta…) — no local accounts to create or revoke manually.
- Immediate revocation: disabling an account in your IdP closes access to Stirling PDF at the same time as the rest of your stack — no orphaned accounts.
- Compliance: access is logged on the IdP side, not in Stirling PDF. Centralized audit trail, no additional configuration required.
- Local form disabled: a single variable (
SECURITY_OAUTH2_AUTO_CREATE_USER=falsecombined with disabling the login form) prevents any SSO bypass. - PKCE support: v3 properly implements the PKCE flow — IdPs that require it (Authentik in particular) work without special configuration.
- Non-destructive update: enabling SSO on an existing instance does not delete processed files or history.
Prerequisites
Before starting:
Stirling PDF ≥ v3.0.0 already deployed. If your instance is running v2.x, update it (docker compose pull && docker compose up -d) and verify with docker compose logs stirling-pdf | grep version.
An operational OIDC identity provider. This guide covers the two most common IdPs in self-hosted stacks: Authentik (a dedicated container, typically on the same VPS) and Keycloak (deployed separately, recommended for multi-application environments). If you don't have an IdP yet, the guide Hosting Authentik on a VPS covers the complete installation.
A reverse proxy with active TLS. Stirling PDF must be served over HTTPS — OAuth2 session cookies are Secure by default. nginx, Caddy, and Traefik all work without modification.
Resources: minimum 1 vCPU / 2 GB RAM. OCR and complex PDF conversion are resource-intensive — plan for 2 vCPU / 4 GB for team use above 5 simultaneous users.
Enabling SSO in Stirling PDF
Update to v3.0.0 or higher
If your
docker-compose.ymlstill points to thefrooodle/s-pdf:latestimage or a pinned version ≤ 2.x, first update the image:docker compose pull stirling-pdf docker compose up -d stirling-pdf docker compose logs stirling-pdf --tail=20Verify that the
Stirling-PDF versionline shows3.0.0or higher before continuing.Add OAuth2 variables to settings.yml
Stirling PDF loads its configuration from
./configs/settings.yml(path of the volume mounted in the compose). Open this file and add or complete thesecurityblock:security: enableLogin: true oauth2: enabled: true provider: oidc issuer: https://authentik.your-domain.com/application/o/stirling-pdf/ clientId: YOUR_CLIENT_ID clientSecret: YOUR_CLIENT_SECRET scopes: openid,profile,email useAsUsername: email autoCreateUser: trueAll six variables are required.
SECURITY_OAUTH2_USE_AS_USERNAMEdetermines which OIDC token field serves as the username in Stirling PDF —emailis the usual choice,preferred_usernamealso works if your IdP provides it.Alternatively, these variables can be passed directly in
docker-compose.ymlunderenvironment:with theSECURITY_OAUTH2_prefix:environment: SECURITY_OAUTH2_ENABLED: "true" SECURITY_OAUTH2_PROVIDER: oidc SECURITY_OAUTH2_ISSUER: https://authentik.your-domain.com/application/o/stirling-pdf/ SECURITY_OAUTH2_CLIENT_ID: YOUR_CLIENT_ID SECURITY_OAUTH2_CLIENT_SECRET: YOUR_CLIENT_SECRET SECURITY_OAUTH2_SCOPES: openid,profile,email SECURITY_OAUTH2_USE_AS_USERNAME: email SECURITY_OAUTH2_AUTO_CREATE_USER: "true"Restart the container and verify logs
Apply the configuration:
docker compose restart stirling-pdf docker compose logs stirling-pdf --follow --tail=30Look for the
OAuth2 SSO enabledline in the startup logs. If you seeError loading OAuth2 issuer metadata, the OIDC discovery endpoint (/.well-known/openid-configuration) is unreachable from the container — verify that theissuerURL is reachable via Docker networking.Then test that the redirect endpoint exists:
curl -I https://pdf.your-domain.com/oauth2/authorization/oidcExpected response:
HTTP/2 302to your IdP's authorization URL. A404means SSO is not activated (variable not read or container not restarted).
Configuring Authentik as identity provider
In the Authentik admin interface (https://authentik.your-domain.com/if/admin/):
1. Create an OAuth2/OIDC Provider
Go to Applications → Providers → Create. Choose OAuth2/OpenID Connect Provider. Give it a name (e.g. stirling-pdf-provider). In the Redirect URIs field, enter exactly:
https://pdf.your-domain.com/login/oauth2/code/oidcEnable PKCE (Proof Key for Code Exchange) if the checkbox is available — Authentik requires it by default since version 2024.x. Leave scopes on openid, profile, email.
Note the generated Client ID and Client Secret — these are the values to copy into settings.yml.
2. Create the Application
Go to Applications → Applications → Create. Name it Stirling PDF, select the Provider created in the previous step. Save.
3. Get the issuer URL
Authentik's OIDC discovery URL follows the pattern:
https://authentik.your-domain.com/application/o/stirling-pdf/Where stirling-pdf is the Application slug (not the Provider). Verify by opening https://authentik.your-domain.com/application/o/stirling-pdf/.well-known/openid-configuration in a browser — you should receive a valid JSON with authorization_endpoint.
Configuring Keycloak as identity provider
In the Keycloak admin console (https://keycloak.your-domain.com/admin/):
1. Select the Realm
Choose the realm that hosts your users (e.g. master for internal use, or a dedicated realm internal-apps).
2. Create an OIDC Client
Go to Clients → Create client. Fill in:
- Client ID: stirling-pdf (free value, but must be reported in settings.yml)
- Client Protocol: openid-connect
- Access Type: confidential
In the Settings tab, add the Redirect URI:
https://pdf.your-domain.com/login/oauth2/code/oidcEnable Standard Flow and disable Implicit Flow.
3. Get the Client Secret
Credentials tab → copy the Secret value.
4. Keycloak issuer URL
The URL follows the pattern:
https://keycloak.your-domain.com/realms/YOUR_REALMVerify by opening https://keycloak.your-domain.com/realms/YOUR_REALM/.well-known/openid-configuration.
Hardening: disable the local login form after SSO
Once SSO is validated and all your users migrated, it is recommended to disable the local password login form — which remains active by default even with OAuth2 enabled. Add to settings.yml:
security:
enableLogin: true
loginMethod: oauth2Disabling the local method prevents any SSO bypass through the form. Keep an emergency admin account in your IdP before applying this configuration — if your IdP becomes unavailable, you will no longer be able to log in.
Troubleshooting common errors
redirect_uri mismatch — The URI registered in the provider does not exactly match what Stirling PDF sends. The expected value is https://pdf.your-domain.com/login/oauth2/code/oidc, no trailing slash, HTTPS required. Check for invisible spaces or characters in your IdP field.
PKCE required or code_challenge_method unsupported — Authentik requires PKCE by default since 2024.x. If your Stirling PDF version is < 3.0.0, it does not support PKCE — update it. On v3, the PKCE flow is natively supported.
Cross-domain cookies lost after IdP redirect — If Stirling PDF is served on a different subdomain from your IdP, check that your reverse proxy is not injecting SameSite=Strict on session cookies. The correct value is SameSite=Lax. Symptom: the redirect from the IdP results in a blank page or redirect loop.
Error loading OAuth2 issuer metadata on startup — The Stirling PDF container cannot reach your IdP's discovery endpoint. Common causes: isolated Docker network (the container cannot resolve the IdP domain name), untrusted self-signed TLS certificate, or IdP is down. Test from the container: docker compose exec stirling-pdf curl -s https://authentik.your-domain.com/application/o/stirling-pdf/.well-known/openid-configuration.
User logs in but sees 403 Forbidden — SECURITY_OAUTH2_AUTO_CREATE_USER is false (default) and the user doesn't yet exist in Stirling PDF. Set it to true while accounts are created on first login, or create users manually from the Stirling PDF admin interface.
SSO at no cost, one block at a time
SSO is no longer a selling point of a paid edition — it is a three-block configuration in a YAML file. v3.0.0 made this change permanent, and v3.1.0 (October 5, 2026) confirms the stability of the new behavior.
If your Stirling PDF instance is exposed to your team without centralized authentication today, the fix takes one container update, three environment variables, and two configuration screens in your IdP. The return: instant revocation, centralized audit trail, and one uncontrolled access vector closed.
To go further on the open source IdPs covered here, the guides Hosting Authentik on a VPS and Authentik, Authelia or Keycloak: choosing your SSO cover the deployment and trade-offs of each solution.
