SSO الخاص بـ Enterprise أصبح مجانياً في v3
يجمع Stirling PDF أكثر من 50 عملية PDF — دمج، تقسيم، ضغط، تحويل تنسيق، OCR، توقيع، إعادة ترتيب الصفحات — في واجهة ويب مستضافة ذاتياً. منذ إطلاقه، نما الأداة على GitHub (87,000 نجمة، ترخيص MIT) وترسّخ كمرجع المصدر المفتوح لمعالجة المستندات في الفرق.
كانت v2 تقسّم المميزات: العمليات الأساسية كانت مجانية، بينما كان SSO OAuth2 وبعض الوظائف المتقدمة محجوزة لباقة Enterprise. هذا النموذج كان منطقياً تجارياً، لكنه أفرز وضعاً غير مريح للفرق المستضيفة ذاتياً: Stirling PDF متاح دون كلمة مرور على منفذ مفتوح، أو بحسابات محلية يستحيل إلغاؤها من دليل مركزي.
اندمجت PR #8137 في سبتمبر 2026 وأعادت تنظيم شبكة المميزات. شحنت v3.0.0 (ملاحظات الإصدار: github.com/Stirling-Tools/Stirling-PDF/releases/tag/v3.0.0) هذا التغيير، المؤكد استقراره في v3.1.0 (5 أكتوبر 2026). النتيجة: SECURITY_OAUTH2_ENABLED=true يعمل على أي تثبيت ≥ v3.0.0، دون مفتاح ترخيص، دون باقة مدفوعة.
ما الذي يغيّره SSO المجاني عملياً
- وصول مركزي: يتحقق جميع أعضاء الفريق عبر مزوّد الهوية الحالي لديك (Authentik، Keycloak، Zitadel، Okta…) — لا حسابات محلية للإنشاء أو الإلغاء يدوياً.
- إلغاء فوري: تعطيل حساب في IdP الخاص بك يغلق الوصول إلى Stirling PDF في نفس الوقت مع بقية مجموعة أدواتك — لا حسابات يتيمة.
- الامتثال: تُسجَّل الوصولات على جانب IdP، لا في Stirling PDF. سجل تدقيق مركزي، دون تهيئة إضافية.
- تعطيل النموذج المحلي: متغير واحد (
SECURITY_OAUTH2_AUTO_CREATE_USER=falseمع تعطيل نموذج تسجيل الدخول) يمنع أي تجاوز لـ SSO. - دعم PKCE: تطبّق v3 تدفق PKCE بصورة صحيحة — تعمل IdPs التي تتطلبه (Authentik بالأخص) دون تهيئة استثنائية.
- تحديث غير مدمّر: تفعيل SSO على مثيل قائم لا يحذف الملفات المعالجة ولا السجل.
المتطلبات الأساسية
قبل البدء:
Stirling PDF ≥ v3.0.0 منشور مسبقاً. إذا كان مثيلك يعمل على v2.x، حدّثه (docker compose pull && docker compose up -d) وتحقق بـ docker compose logs stirling-pdf | grep version.
مزوّد هوية OIDC يعمل. يغطي هذا الدليل أكثر IdP شيوعاً في مجموعات الاستضافة الذاتية: Authentik (حاوية مخصصة، عادة على نفس الـ VPS) وKeycloak (منشور بشكل منفصل، موصى به للبيئات متعددة التطبيقات). إذا لم يكن لديك IdP بعد، يغطي دليل استضافة Authentik على VPS التثبيت الكامل.
بروكسي عكسي مع TLS نشط. يجب تقديم Stirling PDF عبر HTTPS — ملفات تعريف الارتباط لجلسة OAuth2 تحمل Secure افتراضياً. nginx وCaddy وTraefik تعمل جميعها دون تعديل.
الموارد: 1 vCPU / 2 جيجابايت RAM كحد أدنى. OCR وتحويل PDF المعقدة تستهلك الموارد — خطّط لـ 2 vCPU / 4 جيجابايت للاستخدام الجماعي فوق 5 مستخدمين متزامنين.
تفعيل SSO في Stirling PDF
التحديث إلى v3.0.0 أو أحدث
إذا كان
docker-compose.ymlالخاص بك لا يزال يشير إلى صورةfrooodle/s-pdf:latestأو إصدار محدد ≤ 2.x، حدّث الصورة أولاً:docker compose pull stirling-pdf docker compose up -d stirling-pdf docker compose logs stirling-pdf --tail=20تحقق من أن سطر
Stirling-PDF versionيعرض3.0.0أو أعلى قبل المتابعة.إضافة متغيرات OAuth2 في settings.yml
يحمّل Stirling PDF تهيئته من
./configs/settings.yml(مسار الـ volume المُحمَّل في compose). افتح هذا الملف وأضف أو أكمل كتلةsecurity: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: trueالمتغيرات الستة إلزامية. يحدد
SECURITY_OAUTH2_USE_AS_USERNAMEأي حقل من رمز OIDC يُستخدم كاسم مستخدم في Stirling PDF —emailهو الخيار المعتاد،preferred_usernameيعمل أيضاً إذا وفّره IdP الخاص بك.بدلاً من ذلك، يمكن تمرير هذه المتغيرات مباشرة في
docker-compose.ymlتحتenvironment:بالبادئةSECURITY_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"إعادة تشغيل الحاوية والتحقق من السجلات
طبّق التهيئة:
docker compose restart stirling-pdf docker compose logs stirling-pdf --follow --tail=30ابحث عن سطر
OAuth2 SSO enabledفي سجلات بدء التشغيل. إذا رأيتError loading OAuth2 issuer metadata، فإن نقطة اكتشاف OIDC (/.well-known/openid-configuration) غير قابلة للوصول من الحاوية — تحقق من أن URL الـissuerقابل للوصول عبر شبكة Docker.اختبر بعدها أن نقطة إعادة التوجيه موجودة:
curl -I https://pdf.your-domain.com/oauth2/authorization/oidcالاستجابة المتوقعة:
HTTP/2 302نحو URL تفويض IdP الخاص بك. الـ404يعني أن SSO غير مفعّل (متغير لم يُقرأ أو الحاوية لم تُعد تشغيلها).
تهيئة Authentik كمزوّد هوية
في واجهة إدارة Authentik (https://authentik.your-domain.com/if/admin/):
1. إنشاء Provider من نوع OAuth2/OIDC
اذهب إلى Applications → Providers → Create. اختر OAuth2/OpenID Connect Provider. أعطه اسماً (مثلاً stirling-pdf-provider). في حقل Redirect URIs، أدخل بالضبط:
https://pdf.your-domain.com/login/oauth2/code/oidcفعّل PKCE إذا كان مربع الاختيار متاحاً — يتطلبه Authentik افتراضياً منذ الإصدار 2024.x. اترك النطاقات على openid وprofile وemail.
سجّل Client ID وClient Secret المُولَّدَين — هذه هي القيم التي ستنسخها في settings.yml.
2. إنشاء التطبيق
اذهب إلى Applications → Applications → Create. سمّه Stirling PDF، اختر Provider المُنشأ في الخطوة السابقة. احفظ.
3. الحصول على URL الـ issuer
يتبع URL اكتشاف OIDC في Authentik النمط:
https://authentik.your-domain.com/application/o/stirling-pdf/حيث stirling-pdf هو الـ slug للتطبيق (ليس الـ Provider). تحقق بفتح https://authentik.your-domain.com/application/o/stirling-pdf/.well-known/openid-configuration في متصفح — يجب أن تتلقى JSON صالحاً مع authorization_endpoint.
تهيئة Keycloak كمزوّد هوية
في وحدة تحكم إدارة Keycloak (https://keycloak.your-domain.com/admin/):
1. اختيار الـ Realm
اختر الـ realm الذي يستضيف مستخدميك (مثلاً master للاستخدام الداخلي، أو realm مخصص internal-apps).
2. إنشاء عميل OIDC
اذهب إلى Clients → Create client. أدخل:
- Client ID: stirling-pdf (قيمة حرة، لكن يجب الإبلاغ عنها في settings.yml)
- Client Protocol: openid-connect
- Access Type: confidential
في تبويب Settings، أضف Redirect URI:
https://pdf.your-domain.com/login/oauth2/code/oidcفعّل Standard Flow وعطّل Implicit Flow.
3. الحصول على Client Secret
تبويب Credentials ← انسخ قيمة Secret.
4. URL الـ issuer لـ Keycloak
يتبع URL النمط:
https://keycloak.your-domain.com/realms/YOUR_REALMتحقق بفتح https://keycloak.your-domain.com/realms/YOUR_REALM/.well-known/openid-configuration.
التصليب: عطّل نموذج تسجيل الدخول المحلي بعد SSO
بمجرد التحقق من SSO وهجرة جميع المستخدمين، يُنصح بتعطيل نموذج تسجيل الدخول بكلمة مرور المحلية — الذي يبقى نشطاً افتراضياً حتى مع تفعيل OAuth2. أضف في settings.yml:
security:
enableLogin: true
loginMethod: oauth2تعطيل الطريقة المحلية يمنع أي تجاوز لـ SSO عبر النموذج. احتفظ بحساب إداري طارئ في IdP الخاص بك قبل تطبيق هذه التهيئة — إذا أصبح IdP الخاص بك غير متاح، لن تتمكن من تسجيل الدخول.
استكشاف أخطاء الأخطاء الشائعة وإصلاحها
redirect_uri mismatch — الـ URI المسجّل في المزوّد لا يطابق بالضبط ما يرسله Stirling PDF. القيمة المتوقعة هي https://pdf.your-domain.com/login/oauth2/code/oidc، بدون شرطة مائلة في النهاية، HTTPS إلزامي. تحقق من غياب مسافات أو أحرف غير مرئية في حقل IdP الخاص بك.
PKCE required أو code_challenge_method unsupported — يتطلب Authentik PKCE افتراضياً منذ 2024.x. إذا كان إصدار Stirling PDF الخاص بك < 3.0.0، فإنه لا يدعم PKCE — حدّثه. على v3، تدفق PKCE مدعوم أصلاً.
ملفات تعريف الارتباط cross-domain تضيع بعد إعادة توجيه IdP — إذا كان Stirling PDF يُقدَّم على نطاق فرعي مختلف عن IdP الخاص بك، تحقق من أن البروكسي العكسي لا يحقن SameSite=Strict على ملفات تعريف ارتباط الجلسة. القيمة الصحيحة هي SameSite=Lax. العرَض: يؤدي إعادة التوجيه من IdP إلى صفحة بيضاء أو حلقة إعادة تحميل.
Error loading OAuth2 issuer metadata عند بدء التشغيل — حاوية Stirling PDF لا تستطيع الوصول إلى نقطة اكتشاف IdP الخاص بك. الأسباب الشائعة: شبكة Docker معزولة، شهادة TLS ذاتية التوقيع غير موثوق بها، أو IdP متوقف. اختبر من الحاوية: docker compose exec stirling-pdf curl -s https://authentik.your-domain.com/application/o/stirling-pdf/.well-known/openid-configuration.
المستخدم يسجّل الدخول لكنه يرى 403 Forbidden — SECURITY_OAUTH2_AUTO_CREATE_USER يساوي false (الافتراضي) والمستخدم غير موجود بعد في Stirling PDF. اضبطه على true ريثما تُنشأ الحسابات عند أول تسجيل دخول، أو أنشئ المستخدمين يدوياً من واجهة إدارة Stirling PDF.
SSO دون تكلفة، كتلة تلو الأخرى
لم يعد SSO ميزة تسويقية لإصدار مدفوع — إنه تهيئة ثلاث كتل في ملف YAML. جعلت v3.0.0 هذا التغيير دائماً، وتؤكد v3.1.0 (5 أكتوبر 2026) استقرار السلوك الجديد.
إذا كان مثيل Stirling PDF الخاص بك معروضاً على فريقك اليوم دون مصادقة مركزية، فإن الإصلاح يتطلب تحديث حاوية واحدة، وثلاثة متغيرات بيئية، وشاشتين من التهيئة في IdP الخاص بك. العائد: إلغاء فوري، وسجل تدقيق مركزي، وناقل وصول غير محكوم مغلق.
للتعمق أكثر في IdPs المصدر المفتوح المغطاة هنا، تغطي الأدلة استضافة Authentik على VPS وAuthentik أو Authelia أو Keycloak: اختيار SSO الخاص بك نشر كل حل ومقايضاته.
