El SSO de Enterprise pasó a ser gratuito en v3
Stirling PDF reúne más de 50 operaciones PDF — fusión, división, compresión, conversión de formato, OCR, firma, reordenación de páginas — en una interfaz web autoalojada. Desde su creación, la herramienta ha crecido en GitHub (87.000 estrellas, licencia MIT) y se ha consolidado como la referencia de código abierto para el tratamiento documental en equipo.
La v2 compartimentaba las funciones: las operaciones básicas eran libres, el SSO OAuth2 y algunas funciones avanzadas estaban reservadas al plan Enterprise. Este modelo freemium tenía sentido comercial, pero creaba una situación incómoda para los equipos con autoalojamiento: Stirling PDF accesible sin contraseña en un puerto abierto, o con cuentas locales imposibles de revocar desde un directorio central.
La PR #8137 se fusionó en septiembre de 2026 y reorganizó la cuadrícula de funciones. La v3.0.0 (notas de la versión: github.com/Stirling-Tools/Stirling-PDF/releases/tag/v3.0.0) distribuyó este cambio, confirmado estable en la v3.1.0 (5 de octubre de 2026). Resultado: SECURITY_OAUTH2_ENABLED=true funciona en cualquier instalación ≥ v3.0.0, sin clave de licencia, sin plan de pago.
Qué cambia el SSO gratuito en la práctica
- Acceso centralizado: todos los miembros del equipo se autentican a través de tu proveedor de identidad existente (Authentik, Keycloak, Zitadel, Okta…) — sin cuentas locales que crear ni revocar manualmente.
- Revocación inmediata: deshabilitar una cuenta en tu IdP cierra el acceso a Stirling PDF al mismo tiempo que al resto de tu stack — sin cuentas huérfanas.
- Cumplimiento normativo: los accesos se registran en el lado del IdP, no en Stirling PDF. Registro de auditoría centralizado, sin configuración adicional.
- Formulario local deshabilitado: una sola variable (
SECURITY_OAUTH2_AUTO_CREATE_USER=falsecombinada con la desactivación del formulario de inicio de sesión) impide cualquier bypass del SSO. - Soporte PKCE: la v3 implementa correctamente el flujo PKCE — los IdPs que lo requieren (Authentik en particular) funcionan sin configuración especial.
- Actualización no destructiva: activar SSO en una instancia existente no elimina los archivos procesados ni el historial.
Requisitos previos
Antes de empezar:
Stirling PDF ≥ v3.0.0 ya desplegado. Si tu instancia funciona con v2.x, actualízala (docker compose pull && docker compose up -d) y verifica con docker compose logs stirling-pdf | grep version.
Un proveedor de identidad OIDC operativo. Esta guía cubre los dos IdPs más comunes en stacks autoalojadas: Authentik (un contenedor dedicado, normalmente en el mismo VPS) y Keycloak (desplegado por separado, recomendado para entornos con múltiples aplicaciones). Si aún no tienes un IdP, la guía Alojar Authentik en un VPS cubre la instalación completa.
Un proxy inverso con TLS activo. Stirling PDF debe servirse por HTTPS — las cookies de sesión OAuth2 son Secure por defecto. nginx, Caddy y Traefik funcionan todos sin modificación.
Recursos: mínimo 1 vCPU / 2 GB RAM. El OCR y la conversión de PDF complejos son intensivos en recursos — planifica 2 vCPU / 4 GB para uso en equipo con más de 5 usuarios simultáneos.
Activar SSO en Stirling PDF
Actualizar a v3.0.0 o superior
Si tu
docker-compose.ymlsigue apuntando a la imagenfrooodle/s-pdf:latesto a una versión fijada ≤ 2.x, primero actualiza la imagen:docker compose pull stirling-pdf docker compose up -d stirling-pdf docker compose logs stirling-pdf --tail=20Verifica que la línea
Stirling-PDF versionmuestre3.0.0o superior antes de continuar.Añadir las variables OAuth2 en settings.yml
Stirling PDF carga su configuración desde
./configs/settings.yml(ruta del volumen montado en el compose). Abre este archivo y añade o completa el bloquesecurity: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: trueLas seis variables son obligatorias.
SECURITY_OAUTH2_USE_AS_USERNAMEdetermina qué campo del token OIDC sirve como nombre de usuario en Stirling PDF —emailes la elección habitual,preferred_usernametambién funciona si tu IdP lo proporciona.Alternativamente, estas variables pueden pasarse directamente en
docker-compose.ymlbajoenvironment:con el prefijoSECURITY_OAUTH2_: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"Reiniciar el contenedor y verificar los logs
Aplica la configuración:
docker compose restart stirling-pdf docker compose logs stirling-pdf --follow --tail=30Busca la línea
OAuth2 SSO enableden los logs de inicio. Si vesError loading OAuth2 issuer metadata, el endpoint de descubrimiento OIDC (/.well-known/openid-configuration) es inaccesible desde el contenedor — verifica que la URL delissuersea alcanzable vía red Docker.Luego comprueba que el endpoint de redirección existe:
curl -I https://pdf.your-domain.com/oauth2/authorization/oidcRespuesta esperada:
HTTP/2 302hacia la URL de autorización de tu IdP. Un404significa que el SSO no está activado (variable no leída o contenedor no reiniciado).
Configurar Authentik como proveedor de identidad
En la interfaz de administración de Authentik (https://authentik.your-domain.com/if/admin/):
1. Crear un Provider OAuth2/OIDC
Ve a Applications → Providers → Create. Elige OAuth2/OpenID Connect Provider. Dale un nombre (p. ej. stirling-pdf-provider). En el campo Redirect URIs, introduce exactamente:
https://pdf.your-domain.com/login/oauth2/code/oidcActiva PKCE (Proof Key for Code Exchange) si la casilla está disponible — Authentik lo exige por defecto desde la versión 2024.x. Deja los scopes en openid, profile, email.
Anota el Client ID y el Client Secret generados — son los valores que copiarás en settings.yml.
2. Crear la Aplicación
Ve a Applications → Applications → Create. Nómbrala Stirling PDF, selecciona el Provider creado en el paso anterior. Guarda.
3. Obtener la URL del issuer
La URL de descubrimiento OIDC de Authentik sigue el patrón:
https://authentik.your-domain.com/application/o/stirling-pdf/Donde stirling-pdf es el slug de la Aplicación (no del Provider). Verifica abriendo https://authentik.your-domain.com/application/o/stirling-pdf/.well-known/openid-configuration en un navegador — debes recibir un JSON válido con authorization_endpoint.
Configurar Keycloak como proveedor de identidad
En la consola de administración de Keycloak (https://keycloak.your-domain.com/admin/):
1. Seleccionar el Realm
Elige el realm que aloja tus usuarios (p. ej. master para uso interno, o un realm dedicado internal-apps).
2. Crear un Cliente OIDC
Ve a Clients → Create client. Rellena:
- Client ID: stirling-pdf (valor libre, pero debe reportarse en settings.yml)
- Client Protocol: openid-connect
- Access Type: confidential
En la pestaña Settings, añade la Redirect URI:
https://pdf.your-domain.com/login/oauth2/code/oidcActiva Standard Flow y desactiva Implicit Flow.
3. Obtener el Client Secret
Pestaña Credentials → copia el valor de Secret.
4. URL del issuer para Keycloak
La URL sigue el patrón:
https://keycloak.your-domain.com/realms/YOUR_REALMVerifica abriendo https://keycloak.your-domain.com/realms/YOUR_REALM/.well-known/openid-configuration.
Bastionado: desactiva el formulario de inicio de sesión local tras el SSO
Una vez validado el SSO y migrados todos tus usuarios, se recomienda deshabilitar el formulario de inicio de sesión con contraseña local — que permanece activo por defecto incluso con OAuth2 habilitado. Añade en settings.yml:
security:
enableLogin: true
loginMethod: oauth2Deshabilitar el método local impide cualquier bypass del SSO a través del formulario. Mantén una cuenta de administrador de emergencia en tu IdP antes de aplicar esta configuración — si tu IdP queda inaccesible, no podrás iniciar sesión.
Solución de errores frecuentes
redirect_uri mismatch — La URI registrada en el proveedor no coincide exactamente con lo que envía Stirling PDF. El valor esperado es https://pdf.your-domain.com/login/oauth2/code/oidc, sin barra final, HTTPS obligatorio. Comprueba la ausencia de espacios o caracteres invisibles en el campo de tu IdP.
PKCE required o code_challenge_method unsupported — Authentik exige PKCE por defecto desde 2024.x. Si tu versión de Stirling PDF es < 3.0.0, no soporta PKCE — actualízala. En la v3, el flujo PKCE está soportado nativamente.
Cookies cross-domain perdidas tras la redirección del IdP — Si Stirling PDF se sirve en un subdominio diferente al de tu IdP, verifica que tu proxy inverso no inyecte SameSite=Strict en las cookies de sesión. El valor correcto es SameSite=Lax. Síntoma: la redirección desde el IdP produce una página en blanco o un bucle de recarga.
Error loading OAuth2 issuer metadata al iniciar — El contenedor de Stirling PDF no puede alcanzar el endpoint de descubrimiento de tu IdP. Causas frecuentes: red Docker aislada, certificado TLS autofirmado no confiable, o IdP apagado. Prueba desde el contenedor: docker compose exec stirling-pdf curl -s https://authentik.your-domain.com/application/o/stirling-pdf/.well-known/openid-configuration.
El usuario inicia sesión pero ve 403 Forbidden — SECURITY_OAUTH2_AUTO_CREATE_USER está en false (valor predeterminado) y el usuario aún no existe en Stirling PDF. Ponlo en true mientras se crean las cuentas en el primer inicio de sesión, o crea los usuarios manualmente desde la interfaz de administración de Stirling PDF.
SSO sin coste, un bloque a la vez
El SSO ya no es un argumento de venta de una edición de pago — es una configuración de tres bloques en un archivo YAML. La v3.0.0 hizo permanente este cambio, y la v3.1.0 (5 de octubre de 2026) confirma la estabilidad del nuevo comportamiento.
Si tu instancia de Stirling PDF está expuesta a tu equipo hoy sin autenticación centralizada, la corrección requiere una actualización de contenedor, tres variables de entorno y dos pantallas de configuración en tu IdP. El retorno: revocación instantánea, registro de auditoría centralizado y un vector de acceso no controlado cerrado.
Para profundizar en los IdPs de código abierto cubiertos aquí, las guías Alojar Authentik en un VPS y Authentik, Authelia o Keycloak: elegir tu SSO cubren el despliegue y los compromisos de cada solución.
