مرجع پیکربندی 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	خاموش	الزام امضا روی ریشهٔ پاسخ (امضای assertion همیشه الزامی است)
issuer	OIDC	—	URL پایهٔ صادرکننده (برای فعال‌سازی الزامی)
clientId	OIDC	—	شناسهٔ کلاینت عمومی (برای فعال‌سازی الزامی)
clientSecret	OIDC	—	فقط کلاینت‌های محرمانه؛ در فایل رازهای 0600 ذخیره می‌شود، هرگز در پایگاه‌داده — روی RPC فقط‌نوشتنی است (sso.getConfig مقدار clientSecretPresent را گزارش می‌کند)
groupsClaim	OIDC	groups	ادعایی که نام گروه‌ها را حمل می‌کند
defaultRole	هر دو	member	نقشی که وقتی هیچ گروهی نگاشت نمی‌شود اعمال می‌شود — هرگز owner
groupRoleMap	هر دو	{}	گروه → نقش؛ نگاشت‌های مالک هنگام ذخیره رد می‌شوند
autoMember	هر دو	روشن	افزودن خودکار کاربران به همهٔ فضاهای کاری در اولین ورود
allowJit	هر دو	روشن	تأمین کاربران ناشناخته هنگام ورود

پیکربندی فرایند

اتصال‌های 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=…	هیچ (تغییر مسیر)	آغاز ورود آغازشده از SP؛ relay=desktop کار را به برنامه واگذار می‌کند و relay=web-popup به زبانهٔ اتصالِ در انتظار پیام postMessage می‌فرستد (آن زبانه client_origin خود را اعلام می‌کند که تنها وقتی رعایت می‌شود که فهرست مجاز مبدأها به آن اعتماد کند)
POST /saml/acs	هیچ (POST از سوی IdP)	مصرف‌کنندهٔ assertion — تأیید، تأمین، صدور
GET /saml/metadata	هیچ	EntityDescriptor مربوط به SP ما
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)	برای Users: ساخت/گرفتن/فهرست+فیلتر/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	فقط‌خواندنی؛ push گروه طبق طراحی 501 پاسخ می‌دهد
/scim/v2/ServiceProviderConfig	Bearer	سند قابلیت‌ها

عملیات RPC

همهٔ عملیات‌های sso.* در محدودهٔ سرورند و به مالک سرور (به‌کاربرندهٔ این نصب، ServerAuthority.serverOwner) گره خورده‌اند. مالک‌بودن یک فضای کاری کافی نیست؛ جفت‌سازی به‌تنهایی هرگز این دسترسی را نمی‌دهد.

عملیات	هدف
sso.getConfig	اتصال ذخیره‌شده برای یک نوع
sso.saveConfig	اعتبارسنجی، ذخیره و اعمال زنده
sso.status	فلگ‌های فعال/پیکربندی‌شده، وجود توکن SCIM، مبدأ کانونیکال
sso.testConnection	آزمایش یک اتصال بدون رفت‌وبرگشت مرورگر (SAML: تجزیهٔ فراداده + ساخت AuthnRequest؛ OIDC: کشف صادرکننده)، با مقدارهای ذخیره‌نشدهٔ اختیاری روی صفحه
sso.spMetadata	تولید EntityDescriptor مربوط به SP برای یک مبدأ
sso.setPairingEnabled	مجاز/ممنوعکردن جفت‌سازی دستی (کد دعوت، کلید جفت‌سازی)؛ خودداری از خاموش‌کردن آن تا وقتی هیچ اتصال SSO کارآمدی وجود ندارد، از قفل‌شدن حساب جلوگیری می‌کند
sso.sessionPolicy	خواندن حداکثر عمر اعتبارنامهٔ دستگاه و مهلت بیکاری این نصب (دقیقه؛ 0 = تعیین‌نشده)
sso.setSessionPolicy	تعیین آن حدود؛ در بررسی دستگاه اعمال می‌شود، نه اینکه به کلاینت‌ها اعلام شود
sso.scimRegenerateToken	تولید و بازگرداندن توکن bearer مربوط به SCIM (یک‌بار)

کدهای خطای اعتبارسنجی

شکست‌های cc_saml_verify_response یک کد پایدار حمل می‌کنند:

کد	معنا
signature	امضای گمشده/غیرقابل‌اعتماد/دستکاری‌شده، یا الگوریتم/تبدیلی که مجاز نیست
expired	بیرون از NotBefore/NotOnOrAfter (فراتر از انحراف مجاز)
audience	محدودیت audience ما را نام نمی‌برد
destination	مقصد پاسخ همان ACS ما نیست
request_match	InResponseTo با هیچ درخواست در انتظاری مطابقت ندارد، یا پاسخ ناخواسته است در حالی که ناخواسته‌ها مجاز نیستند
issuer	صادرکننده همان IdP پیکربندی‌شده نیست
recipient	گیرندهٔ تأیید subject همان ACS ما نیست
malformed	شکست در سطح XML/شِما
status	وضعیت گزارش‌شدهٔ IdP «Success» نبود
invalid / internal	هر چیز دیگر / شکست درز

سطوح پایگاه‌داده

• sso_connections (global.db) — یک ردیف به‌ازای هر نوع، طبق طراحی میان همهٔ فضاهای کاری.
• users.sso_subject + users.sso_issuer — سنجاق subject ارائه‌دهنده، به‌ازای هر (issuer, subject) از طریق یک ایندکس جزئی یکتا.
• users.deactivated_at — مُهر غیرفعال‌سازی SCIM.
• توکن bearer مربوط به SCIM و راز کلاینت OIDC در فایل رازهای 0600 زندگی می‌کنند، هرگز در پایگاه‌داده.