OIDC / الدخول الموحّد

تدعم SnapOtter بروتوكول OpenID Connect (OIDC) للدخول الموحّد. يمكن للمستخدمين تسجيل الدخول بمزوّد هوية خارجي مثل Keycloak أو Authentik أو Google أو Microsoft Entra ID بدلاً من (أو إلى جانب) مصادقة اسم المستخدم/كلمة المرور المحلية.

انظر أيضًا

SAML SSO | توفير SCIM | المستخدمون والأدوار والأذونات

بداية سريعة

أضف متغيرات البيئة هذه إلى docker-compose.yml:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

عنوان URI لإعادة التوجيه لمزوّدك هو دائمًا:

${EXTERNAL_URL}/api/auth/oidc/callback

على سبيل المثال، إذا كان EXTERNAL_URL يساوي https://photos.example.com، فاضبط عنوان URI لإعادة التوجيه لمزوّدك على https://photos.example.com/api/auth/oidc/callback.

مرجع الإعداد

المتغير	الافتراضي	الوصف
OIDC_ENABLED	false	تفعيل تسجيل الدخول عبر OIDC. يظهر زر "تسجيل الدخول عبر SSO" على صفحة تسجيل الدخول.
OIDC_ISSUER_URL		عنوان URL لمُصدِّر المزوّد. يجب أن يدعم اكتشاف OIDC (/.well-known/openid-configuration).
OIDC_CLIENT_ID		معرّف عميل OAuth المسجَّل لدى مزوّدك.
OIDC_CLIENT_SECRET		سر عميل OAuth.
OIDC_SCOPES	openid profile email	قائمة نطاقات مفصولة بمسافات لطلبها.
OIDC_AUTO_CREATE_USERS	true	إنشاء حساب مستخدم محلي تلقائيًا عند أول تسجيل دخول عبر OIDC.
OIDC_DEFAULT_ROLE	user	الدور المخصَّص لمستخدمي OIDC المُنشأين تلقائيًا. واحد من admin أو editor أو user.
OIDC_AUTO_LINK_USERS	false	ربط هوية OIDC بمستخدم محلي موجود إذا تطابق عنوان البريد الإلكتروني.
OIDC_PROVIDER_NAME		الاسم المعروض على زر تسجيل الدخول (مثل "Keycloak" أو "Google"). إذا كان فارغًا، يقول الزر "SSO".
OIDC_CLOCK_TOLERANCE	30	تسامح انحراف الساعة بالثواني للتحقق من صحة الرمز.
OIDC_USERNAME_CLAIM	preferred_username	مطالبة رمز الهوية المستخدمة كاسم مستخدم للحسابات الجديدة.
EXTERNAL_URL		عنوان URL العام حيث يمكن الوصول إلى SnapOtter. مطلوب لكي يبني OIDC عنوان URI الصحيح لإعادة التوجيه.
COOKIE_SECRET	يُنشأ تلقائيًا	سر لتوقيع ملفات تعريف ارتباط الجلسة. اضبط هذا صراحةً عند تشغيل نسخ متماثلة متعددة.

أدلة المزوّدين

Keycloak

1. أنشئ عالَمًا جديدًا (أو استخدم عالَمًا موجودًا).
2. انتقل إلى Clients وأنشئ عميلاً جديدًا:
   • Client ID: snapotter
   • Client authentication: On (سري)
   • Authentication flow: Standard flow (Authorization Code)
3. ضمن علامة تبويب Settings للعميل، اضبط Valid redirect URIs على عنوان رد الاتصال الخاص بك (مثل https://photos.example.com/api/auth/oidc/callback).
4. انسخ Client secret من علامة تبويب Credentials.
5. اضبط OIDC_ISSUER_URL على https://keycloak.example.com/realms/your-realm.

Authentik

1. في واجهة المسؤول، انتقل إلى Applications > Providers وأنشئ OAuth2/OpenID Provider جديدًا.
   • Client type: Confidential
   • Redirect URIs: عنوان رد الاتصال الخاص بك
   • Signing key: اختر مفتاحًا موجودًا أو أنشئ واحدًا
2. أنشئ Application واربطه بالمزوّد.
3. انسخ Client ID وClient Secret من إعدادات المزوّد.
4. اضبط OIDC_ISSUER_URL على https://authentik.example.com/application/o/snapotter/ (الشرطة المائلة اللاحقة مهمة).

Google

1. انتقل إلى Google Cloud Console.
2. أنشئ مشروعًا (أو اختر مشروعًا موجودًا).
3. انتقل إلى APIs & Services > OAuth consent screen واضبطه.
4. انتقل إلى APIs & Services > Credentials وأنشئ OAuth 2.0 Client ID:
   • Application type: Web application
   • Authorized redirect URIs: عنوان رد الاتصال الخاص بك
5. انسخ Client ID وClient secret.
6. اضبط OIDC_ISSUER_URL على https://accounts.google.com.
7. اضبط OIDC_USERNAME_CLAIM على email (لا توفّر Google preferred_username).

Azure AD / Entra ID

1. في بوابة Azure، انتقل إلى Microsoft Entra ID > App registrations > New registration.
2. سمِّ التطبيق "SnapOtter". ضمن Redirect URI، اختر منصة Web وأدخل عنوان رد الاتصال الخاص بك (مثل https://photos.example.com/api/auth/oidc/callback). لا تختر Single-page application: تصادق SnapOtter باستخدام سر عميل، وهو ما يرفضه Entra ID في تسجيلات SPA.
3. انسخ Application (client) ID وDirectory (tenant) ID من صفحة Overview.
4. انتقل إلى Certificates & secrets > New client secret وانسخ قيمة السر Value على الفور. تُعرض هذه القيمة مرة واحدة فقط، وSecret ID المجاور لها ليس هو السر.
5. اضبط OIDC_ISSUER_URL على https://login.microsoftonline.com/<tenant-id>/v2.0، مستخدمًا Directory (tenant) ID من الخطوة 3.
6. اترك OIDC_USERNAME_CLAIM على قيمته الافتراضية. يوفّر Entra ID المطالبة preferred_username، لذا لا حاجة هنا إلى تجاوز email المذكور في دليل Google.

استخدم دائمًا معرّف المستأجر الخاص بك في عنوان URL للمُصدِّر، وليس common أو organizations. تعلن نقاط النهاية متعددة المستأجرين هذه القالب الحرفي {tenantid} كمُصدِّر لها، وهو ما يُفشل التحقق من صحة اكتشاف OIDC.

WARNING

تتبع مطالبة preferred_username في Entra ID اسم المستخدم الأساسي (user principal name)، وهو يتغيّر عند إعادة تسمية المستخدم أو نقله إلى مستأجر آخر. تقرأ SnapOtter المطالبة مرة واحدة عند أول تسجيل دخول، لذا يحتفظ الحساب باسم المستخدم الأصلي بعد ذلك. يستمر تسجيل الدخول في العمل في كلتا الحالتين: تجري مطابقة المستخدمين العائدين عبر الموضوع الثابت (subject) في الرمز، وليس عبر اسم المستخدم.

لا يؤدي التحوّل إلى Entra ID إلى إيقاف تسجيل الدخول بكلمة المرور. راجع تعطيل تسجيل الدخول المحلي.

Okta والمزوّدون الآخرون

يعمل أي مزوّد يدعم اكتشاف OIDC بالطريقة نفسها: أنشئ عميل ويب سريًا بعنوان رد الاتصال الخاص بك، ثم وجّه OIDC_ISSUER_URL إلى المُصدِّر. بالنسبة إلى Okta، أنشئ تطبيقًا بطريقة تسجيل الدخول OIDC - OpenID Connect ونوع Web Application، ثم استخدم نطاق Okta الخاص بك كمُصدِّر (مثل https://your-company.okta.com).

لا تُطابق SnapOtter مجموعات مزوّد الهوية مع الأدوار. يحصل مستخدمو SSO الجدد على OIDC_DEFAULT_ROLE، ويغيّر المسؤولون الأدوار ضمن Settings > Users، وطلب مطالبات المجموعات عبر OIDC_SCOPES ليس له أي تأثير.

توفير المستخدمين

الإنشاء التلقائي

عندما يكون OIDC_AUTO_CREATE_USERS يساوي true (الافتراضي)، يُنشأ حساب مستخدم محلي أول مرة يسجّل فيها شخص الدخول عبر OIDC. يُؤخذ اسم المستخدم من المطالبة المحددة بواسطة OIDC_USERNAME_CLAIM، ويُضبط الدور على OIDC_DEFAULT_ROLE.

إذا حدث تعارض في اسم المستخدم، يُضاف لاحقة رقمية (مثلاً يصبح jane هو jane_2).

الربط التلقائي

عندما يكون OIDC_AUTO_LINK_USERS يساوي true، تربط SnapOtter هوية OIDC بحساب محلي موجود إذا تطابقت عناوين البريد الإلكتروني. هذا مفيد عندما يكون لديك حسابات مستخدمين مُنشأة مسبقًا وتريدها أن تبدأ باستخدام SSO من دون فقدان بياناتها.

WARNING

فعّل الربط التلقائي فقط إذا كنت تثق في أن مزوّد OIDC يتحقق من عناوين البريد الإلكتروني. قد يسمح بريد إلكتروني غير موثَّق لشخص ما بالاستيلاء على حساب مستخدم آخر.

تعطيل تسجيل الدخول المحلي

لا يعطّل OIDC تسجيل الدخول المحلي باسم المستخدم/كلمة المرور. تظل كلتا الطريقتين متاحتين. لا يزال بإمكان المسؤولين تسجيل الدخول ببيانات الاعتماد المحلية إذا تعذّر الوصول إلى مزوّد OIDC.

الشهادات الموقَّعة ذاتيًا

إذا كان مزوّد OIDC الخاص بك يستخدم شهادة موقَّعة ذاتيًا أو شهادة مرجع مصادقة خاص، فركّب حزمة مرجع المصادقة داخل الحاوية ووجّه NODE_EXTRA_CA_CERTS إليها:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

DANGER

لا تضبط NODE_TLS_REJECT_UNAUTHORIZED=0. يؤدي هذا إلى تعطيل جميع عمليات التحقق من TLS ويشكّل خطرًا أمنيًا.

مُصدِرو http غير المشفّر

يقبل SnapOtter عنوان مُصدِر يبدأ بـ http:// فقط عندما يكون EXTERNAL_URL أيضًا http غير مشفّر، وهذا يناسب إعداد اختبار محليًا أو على شبكة LAN. عندها تنتقل عملية الاكتشاف وتبادل رمز تسجيل الدخول والرموز المميزة عبر الشبكة دون تشفير، لذلك يسجّل SnapOtter تحذيرًا عند بدء التشغيل يذكر اسم مضيف المُصدِر. ومع EXTERNAL_URL يبدأ بـ https://، يُرفض المُصدِر الذي يستخدم http عند تسجيل الدخول، ويذكر تحذير بدء التشغيل ذلك. وفي الحالتين، الحل هو تقديم موفّر الهوية عبر https.

استكشاف الأخطاء وإصلاحها

عدم تطابق عنوان URI لإعادة التوجيه

أكثر الأخطاء شيوعًا. تحقق من هذه الاختلافات بين ما يتوقعه مزوّدك وما ترسله SnapOtter:

• http مقابل https - يجب أن يتطابق المخطط تمامًا
• الشرطة المائلة اللاحقة - بعض المزوّدين صارمون بشأن هذا
• رقم المنفذ - أدرج المنفذ إذا كان غير قياسي
• المسار - يجب أن يكون /api/auth/oidc/callback

تحقق مرتين من EXTERNAL_URL. يجب أن يتطابق مع عنوان URL الذي يكتبه المستخدمون في متصفحهم.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

يستخدم مزوّد OIDC شهادة لا يثق بها Node.js. راجع الشهادات الموقَّعة ذاتيًا أعلاه.

أخطاء انحراف الساعة

إذا كانت ساعة خادمك وساعة مزوّد OIDC غير متزامنتين، فقد يفشل التحقق من صحة الرمز. زِد OIDC_CLOCK_TOLERANCE (الافتراضي 30 ثانية). الحل الأفضل هو تشغيل NTP على كلا الجهازين.

"مزوّد OIDC غير قابل للوصول"

تجلب SnapOtter مستند اكتشاف المزوّد عند بدء التشغيل وأثناء تسجيل الدخول. تحقق من:

• تحليل DNS من داخل حاوية Docker (docker exec snapotter nslookup auth.example.com)
• قواعد جدار الحماية بين الحاوية والمزوّد
• قيمة OIDC_ISSUER_URL - يجب أن تكون قابلة للوصول من الخادم، وليس فقط من متصفحك

مطالبات مفقودة

إذا كانت أسماء المستخدمين أو عناوين البريد الإلكتروني فارغة بعد تسجيل الدخول، فقد لا يُرجع مزوّدك المطالبات المتوقعة. تحقق من:

• النطاقات المضبوطة في OIDC_SCOPES تتضمن profile وemail
• أن المزوّد مضبوط لتضمين المطالبة المحددة في OIDC_USERNAME_CLAIM في رمز الهوية
• يتطلب بعض المزوّدين إعداد مُخطِّط/نطاق صريحًا لإطلاق المطالبات