مرجع تهيئة SSO

كل ما يُضبط في تسجيل الدخول الموحّد، في موضع واحد. تعيش القيم في صفوف sso_connections داخل global.db (على نطاق الخادم عن قصد)، وتُحرَّر عبر الإعدادات ← الخادم ← تسجيل الدخول الموحّد أو عمليات RPC sso.*. الصف المحفوظ هو مصدر الحقيقة الوحيد — لا مسار بيئة CC_SAML_* / CC_OIDC_* (الاتصال الذي قد يصل من موضعين هو اتصال قد تخالفه شاشة الإعدادات).

حقول الاتصال

الحقل	ينطبق على	الافتراضي	المعنى
enabled	كلاهما	مطفأ	يجوز لتسجيلات الدخول استخدام هذا الاتصال
idpMetadataXml	SAML	—	XML من نوع EntityDescriptor لدى IdP (مطلوب للتفعيل)
spEntityId	SAML	<origin>/saml	معرّف الكيان لدينا، يُثبَّت حين يتغيّر الأصل
emailAttribute	SAML	email	السمة التي تحمل البريد الإلكتروني؛ وNameID على هيئة بريد هو البديل
displayNameAttribute	SAML	displayName	سمة اسم العرض
groupsAttribute	SAML	groups	سمة أسماء المجموعات
clockSkewSeconds	SAML	90	هامش انحراف الساعة عند التحقق من مدة الصلاحية
allowIdpInitiated	SAML	مطفأ	قبول الاستجابات غير المطلوبة (بلا InResponseTo)
wantResponseSigned	SAML	مطفأ	اشتراط توقيع على جذر Response (توقيعات التأكيد مطلوبة دائمًا)
issuer	OIDC	—	عنوان URL الأساسي للمُصدِر (مطلوب للتفعيل)
clientId	OIDC	—	معرّف العميل العام (مطلوب للتفعيل)
clientSecret	OIDC	—	للعملاء السرّيين فقط؛ يُخزَّن في ملف الأسرار بصلاحية 0600، ولا يدخل قاعدة البيانات أبدًا — للكتابة فقط عبر RPC (تبلّغ sso.getConfig عن clientSecretPresent)
groupsClaim	OIDC	groups	المطالبة التي تحمل أسماء المجموعات
defaultRole	كلاهما	member	الدور إن لم تُطابق أي مجموعة — ولا يكون owner أبدًا
groupRoleMap	كلاهما	{}	مجموعة → دور؛ تُرفض تعيينات المالك عند الحفظ
autoMember	كلاهما	مفعّل	إضافة المستخدمين تلقائيًا إلى كل مساحة عمل عند أول تسجيل دخول
allowJit	كلاهما	مفعّل	توفير JIT للمستخدمين المجهولين عند تسجيل الدخول

تهيئة العملية

لا تُبذَر اتصالات SSO من البيئة. العلم المتبقي الوحيد في العملية يخص تسليم المتصفح، لا صف الاتصال:

المتغير / العلم	المعنى
--web-client-url / CC_SERVER_WEB_CLIENT_URL	الأصل الذي تعيد إليه استدعاءات SSO المتصفح (تسير بيانات الاعتماد في جزء عنوان URL). إن تُرك بلا تعيين يبقى التسليم على الأصل نفسه.

يجب أن يكون عنوان URL للمُصدِر نفسه https (يُقبل http لمُصدِري الاسترجاع localhost و127.0.0.1 و::1 فقط).

نقاط نهاية HTTP

نقطة النهاية	المصادقة	الغرض
GET /saml/login?relay=…	بلا مصادقة (إعادة توجيه)	بدء تسجيل الدخول المبدوء من موفّر الخدمة؛ يسلّم relay=desktop إلى التطبيق، ويرسل relay=web-popup رسالة postMessage إلى علامة تبويب الاتصال المنتظرة (التي تعلن client_origin الخاص بها، ولا يُؤخَذ به إلا حين تثق به قائمة السماح للأصول)
POST /saml/acs	بلا مصادقة (POST من IdP)	مستهلك التأكيد — يتحقق ويوفّر ويصكّ
GET /saml/metadata	بلا مصادقة	EntityDescriptor لموفّر الخدمة لدينا
GET /oidc/login?relay=… / GET /oidc/callback	بلا مصادقة	جولة OIDC ذهابًا وإيابًا؛ يسلّم relay=desktop إلى التطبيق، وrelay=web-popup إلى علامة تبويب الاتصال المنتظرة (عرف client_origin نفسه)
GET /auth/providers	بلا مصادقة، CORS *	مسبار شاشة الاتصال: اتصالات SSO المعروضة (id/kind/label) مع pairingEnabled
/scim/v2/Users…	Bearer (رمز SCIM)	إنشاء وجلب وسرد مع تصفية وPUT وPATCH وDELETE للمورد Users
/scim/v2/Groups	Bearer	للقراءة فقط؛ دفع المجموعات يجيب بـ 501 عن قصد
/scim/v2/ServiceProviderConfig	Bearer	مستند القدرات

عمليات RPC

كل عمليات sso.* على نطاق الخادم، ومقصورة على مالك الخادم (مشغّل التثبيت، ServerAuthority.serverOwner). امتلاك مساحة عمل لا يكفي، والاقتران وحده لا يمنحها أبدًا.

العملية	الغرض
sso.getConfig	الاتصال المحفوظ لنوع بعينه
sso.saveConfig	التحقق والحفظ والتطبيق الفوري
sso.status	أعلام التفعيل والتهيئة، ووجود رمز وصول SCIM، والأصل المعياري
sso.testConnection	اختبار اتصال من غير جولة المتصفح ذهابًا وإيابًا (SAML: تحليل البيانات الوصفية وبناء AuthnRequest؛ OIDC: اكتشاف المُصدِر)، ويمكن تمرير قيم ظاهرة على الشاشة لم تُحفَظ
sso.spMetadata	إصدار EntityDescriptor لموفّر الخدمة لأصل بعينه
sso.setPairingEnabled	السماح بالاقتران اليدوي أو منعه (رموز الدعوة ومفاتيح الاقتران)؛ ويرفض التعطيل ما دام لا يوجد اتصال SSO عامل، حذرًا من انغلاق المشغّل خارج الخادم
sso.sessionPolicy	قراءة الحد الأقصى لعمر بيانات اعتماد الجهاز ومهلة الخمول لهذا التثبيت (بالدقائق؛ 0 = بلا تعيين)
sso.setSessionPolicy	تعيين تلك الحدود؛ تُفرَض عند فحص الجهاز، ولا تُعلَن للعملاء
sso.scimRegenerateToken	توليد رمز وصول bearer لـ SCIM وإعادته (مرة واحدة)

رموز أخطاء التحقق

تحمل إخفاقات cc_saml_verify_response رمزًا ثابتًا:

الرمز	المعنى
signature	توقيع مفقود أو غير موثوق أو عُبث به، أو خوارزمية أو تحويل غير مسموح به
expired	خارج NotBefore/NotOnOrAfter (بعد تجاوز انحراف الساعة)
audience	قيد الجمهور لا يسمّينا
destination	وجهة الاستجابة ليست ACS لدينا
request_match	InResponseTo لا يطابق طلبًا معلّقًا، أو الاستجابة غير مطلوبة بينما ذلك ممنوع
issuer	المُصدِر ليس IdP المُهيَّأ
recipient	مستلم تأكيد الموضوع ليس ACS لدينا
malformed	إخفاق على مستوى XML أو المخطط
status	الحالة التي أبلغ عنها IdP لم تكن Success
invalid / internal	أي شيء آخر / إخفاق في الوصلة

أسطح قاعدة البيانات

• sso_connections (global.db) — صف واحد لكل نوع، يعبر مساحات العمل عن قصد.
• users.sso_subject + users.sso_issuer — تثبيت المعرّف الثابت لدى الموفّر، فريد لكل (issuer, subject) عبر فهرس جزئي.
• users.deactivated_at — ختم التعطيل في SCIM.
• يعيش رمز وصول bearer لـ SCIM وسر عميل OIDC في ملف الأسرار بصلاحية 0600، ولا يدخلان قاعدة البيانات أبدًا.