كيفية إعداد تسجيل الدخول الموحد (SSO) باستخدام Keycloak في Element Web

لا يقوم Element Web بالمصادقة مباشرةً مع Keycloak. يستعلم Element من خادم Matrix الرئيسي عن طرق تسجيل الدخول المدعومة؛ يُكمل الخادم الرئيسي عملية OpenID Connect (OIDC) مع Keycloak، ثم يُعيد المستخدم إلى Element. بالنسبة لنشر Synapse باستخدام دعم OIDC المدمج، قم بتكوين عميل OIDC سري في Keycloak، وأضف هذا الموفر إلى Synapse، ويمكنك اختياريًا تعديل إعدادات Element Web config.jsonلعرض أو بدء تسجيل الدخول الموحد (SSO) تلقائيًا.

يستخدم هذا الدليل موفر OIDC المدمج في Synapse، وهو مسار نشر شائع. إذا كان خادمك المنزلي يُفوّض المصادقة إلى خدمة مصادقة المصفوفة (MAS)، فاستخدم رد نداء MAS وتكوين الموفر الموضح أدناه. يختلف عنوانا URL لرد النداء. تمت مراجعة التعليمات بالرجوع إلى وثائق تكوين Element Web، ودليل Synapse v1.144 OIDC، ودليل MAS الحالي لتسجيل الدخول الموحد (SSO)، ودليل إدارة Keycloak 26.8.0 بتاريخ 6 أكتوبر 2026؛ قد تختلف حزم النشر وتسميات واجهة المستخدم حسب الإصدار.

أولاً، حدد مسار المصادقة الذي تستخدمه

راجع وثائق تكوين ونشر Synapse قبل إنشاء عميل. يجب أن ينتمي رد الاتصال إلى المكون الذي يتصل بـ Keycloak؛ لا تُسجّل عنوان موقع Element الإلكتروني كرد اتصال.

ما تحتاج إليه

• عنوان URL عام لبروتوكول HTTPS لـ Synapse، مثل https://matrix.example.com، ومصدر نطاق Keycloak يمكن الوصول إليه، مثل https://sso.example.com/realms/company.
• الوصول الإداري إلى نطاق Keycloak وتكوين Synapse والخدمة.
• نسخة احتياطية من التكوين الحالي وطريقة لاستخدام سجلات Synapse أو وحدة تحكم الخادم في حالة فشل تسجيل الدخول.
• قرار بشأن توفير الحسابات: أي مستخدمي Keycloak يمكنهم تسجيل الدخول، وأي مطالبة تحدد هويتهم، وما إذا كان يجب الاحتفاظ بحسابات Matrix الحالية.

تكوين Keycloak لـ Synapse OIDC

1. إنشاء عميل سري لـ OIDC

في نطاق حسابات Matrix، أنشئ عميلًا لـ Synapse باستخدام بروتوكول OpenID Connect. فعّل رمز التفويض أو التدفق القياسي ومصادقة العميل حتى يتمكن Synapse من استخدام سر العميل عند نقطة نهاية الرمز المميز. عيّن معرّف العميل إلى قيمة ستستخدمها أيضًا في Synapse، على سبيل المثال synapse.

قم بتعيين عنوان URI لإعادة التوجيه الصحيح إلى رد الاتصال الخاص بـ Synapse:

https://matrix.example.com/_synapse/client/oidc/callback

استبدل اسم المضيف المذكور في المثال بعنوان URL الأساسي العام المُهيأ فعليًا لـ Synapse. تجنب استخدام أحرف البدل العامة كما هو الحال *في بيئة الإنتاج. يتحقق Keycloak من صحة عناوين URI لإعادة التوجيه، لذا فإن أي اختلاف في اسم المضيف أو المخطط أو المسار أو الشرطة المائلة الأخيرة قد يتسبب في ظهور خطأ "عنوان URI لإعادة التوجيه غير مسموح به".

احفظ بيانات العميل، وانسخ السرّ المُنشأ، وخزّنه كسرّ على الخادم. احرص على إبقائه بعيدًا عن الملفات العامة لـ Element Web config.json، ونظام التحكم في الإصدارات، ولقطات الشاشة، وجافا سكريبت على جانب العميل. قد تختلف تسمية بيانات اعتماد العميل أو بيانات المصادقة في لوحة تحكم Keycloak الإدارية بين الإصدارات؛ لذا تأكد من أن بيانات العميل الناتجة سرية ويمكنها استخدام آلية رمز التفويض القياسية.

2. تأكيد الجهة المصدرة والمطالبات

يُحدد المُصدر النطاق، وليس جذر خادم Keycloak. في هذا المثال، استخدم https://sso.example.com/realms/company. تأكد من إمكانية الوصول إلى إعدادات OpenID الخاصة بالنطاق على <issuer>/.well-known/openid-configurationوأن المُصدر المُعلن عنه يطابق القيمة التي ستُقدمها إلى Synapse تمامًا.

يحتاج Synapse إلى هوية ثابتة لربط حساب Keycloak بمستخدم Matrix. عادةً ما يُعرّف موفر OIDC الخاص به المستخدم الخارجي باستخدام هوية OIDC؛ ويستخدم تعيين اسم المستخدم أدناه preferred_usernameالجزء المحلي من Matrix. تأكد من أن Keycloak يُعيد هذه الهوية بالفعل، وأن أسماء المستخدمين فريدة وثابتة وفقًا لسياسة حسابك. إذا كانت مؤسستك تسمح بتغيير أسماء المستخدمين، فاختر استراتيجية تعيين واختبرها قبل بدء التشغيل؛ إذ قد يؤثر أي تغيير غير متوقع في التعيين على حساب Matrix الذي يصل إليه المستخدم.

تهيئة المشبك العصبي

3. أضف موفر OIDC

أضف مدخلًا لمزود الخدمة إلى إعدادات Synapse الرئيسية، عادةً ما يكون ملف YAML homeserver.yaml. ادمجه مع ملف YAML الحالي بدلًا من استبدال الإعدادات الأخرى. استبدل مُصدر نطاقك وسر العميل الحقيقي.

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

تتحكم النطاقات المطلوبة في معلومات المستخدم التي قد يُعيدها Keycloak؛ ولا تضمن هذه النطاقات تعبئة جميع البيانات المطلوبة. إذا لم تكن بحاجة إلى استيراد البريد الإلكتروني أو اسم العرض، فقلل النطاقات والتعيين وفقًا لذلك. اجعل ملف التكوين قابلاً للقراءة فقط من قِبل مسؤول الخدمة وعملية Synapse، بما يتناسب مع بيئة النشر الخاصة بك. إذا كنت تُدير Synapse من خلال حاويات أو مخطط، فضع إعدادات الموفر في مصدر التكوين المدعوم بدلاً من تعديل ملف مُنشأ سيتم استبداله.

4. يمكنك اختيارياً ضبط تسجيل الخروج من القناة الخلفية

بشكل افتراضي، لا يؤدي تسجيل الخروج من خدمة واحدة بالضرورة إلى إنهاء جلسة المتصفح لجميع الخدمات الأخرى. إذا كنت ترغب في أن تُنهي إشعارات تسجيل الخروج من Keycloak جلسة Synapse، فقم بتفعيلها backchannel_logout_enabled: trueضمن موفر Keycloak في Synapse، ثم اضبط عنوان URL لتسجيل الخروج من القناة الخلفية لـ Keycloak على:

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

هذا الإجراء اختياري ويعتمد على سياسة تسجيل الخروج وإعدادات العميل. اختبر كلا طريقتي تسجيل الخروج: تسجيل الخروج من Synapse وتسجيل الخروج من Keycloak. لا تفترض أن تسجيل الخروج من Element وحده ينهي جلسة Keycloak.

5. أعد تشغيل برنامج Synapse واختبره

تحقق من صحة ملف YAML باستخدام فحوصات تكوين النشر، ثم أعد تشغيل Synapse أو أعد تحميله باستخدام الطريقة التي تدعمها حزمة أو حاوية الإعداد. راجع سجلات Synapse بحثًا عن أخطاء في اكتشاف OIDC، أو مصادقة العميل، أو رد الاتصال، أو تعيين المطالبات. استخدم حسابًا تجريبيًا أولًا وتأكد من أن معرّف المصفوفة واسم العرض الخاص به هما القيم المتوقعة.

تكوين عنصر الويب

6. اجعل خاصية تسجيل الدخول الموحد اختيارية أو أعد التوجيه تلقائيًا

بمجرد أن يُعلن Synapse عن تسجيل الدخول عبر OIDC، يُمكن لـ Element Web عرض خيار تسجيل الدخول الموحد (SSO). يتحكم إعداد Element sso_redirect_optionsفي تجربة المتصفح؛ فهو لا يُهيئ Keycloak ولا يخزن سر العميل. أضف إعدادًا كهذا إلى إعدادات Element Web المُقدمة config.jsonإذا كنت ترغب في توجيه الزوار غير المُصادق عليهم الذين يصلون إلى صفحة الترحيب أو تسجيل الدخول إلى مسار تسجيل الدخول الموحد المُتاح.

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

في حال تطلّب النشر تسجيل دخول موحّد (SSO) فقط، فعّل خيار "immediate": trueبدء تسجيل الدخول الموحّد لجميع المستخدمين غير المصادق عليهم. قد يُصعّب ذلك الوصول إلى كلمة المرور أو خيارات تسجيل الدخول الأخرى، لذا اختبر استعادة الوصول وصلاحيات المسؤول قبل تطبيقه. إذا كان على المستخدمين الاختيار بين تسجيل الدخول الموحّد وطريقة أخرى، فاترك إعادة التوجيه التلقائي معطّلة، واختبر ظهور خيار تسجيل الدخول الموحّد في مسار تسجيل الدخول.

إذا كان برنامج Synapse يستخدم خدمة مصادقة المصفوفة

MAS هي خدمة مصادقة منفصلة، ​​ويمكنها العمل كعميل OIDC لـ Keycloak. في هذه البنية، قم بتكوين عنوان URI لإعادة توجيه Keycloak على النحو التالي https://auth.example.com/upstream/callback/<provider-id>: حيث يتطابق مُعرّف المزوّد مع تكوين MAS. قم بتكوين المزوّد ضمن MAS upstream_oauth2.providers؛ ثم يستخدم العنصر تدفق المصادقة القائم على MAS الخاص بالخادم الرئيسي. لا تستخدم Synapse /_synapse/client/oidc/callbackلهذا الاتصال بالخادم. يتطلب MAS مزوّد OIDC يدعم تدفق رمز التفويض. يختلف تنسيق تكوينه ومعرّف المزوّد المطلوب وخطوات الترحيل عن تنسيق Synapse المدمج oidc_providers.

سوء الفهم الشائع وحلوله

• كل ما عليّ فعله هو تغيير إعدادات Element. يتحكم Element في تدفق المتصفح، بينما يتولى Synapse أو MAS معالجة OIDC. قم أولاً بضبط موفر الخادم الرئيسي الصحيح.
• يُثبت تسجيل الدخول الناجح إلى Keycloak صحة ربط الحساب. قد تنجح عملية المصادقة حتى مع تحديد جزء محلي أو ملف تعريف خاطئ. اختبر ذلك باستخدام حساب مستخدم غير مُستخدم في بيئة الإنتاج، وتحقق من مُعرّف المصفوفة الناتج.
• "يؤدي تسجيل الدخول الموحد (SSO) إلى تعطيل كلمات المرور والتسجيل تلقائيًا." تخضع هذه السياسات لسيطرة الخادم الرئيسي وعملية النشر. راجع إعدادات تسجيل الدخول والتسجيل في Synapse بشكل منفصل، وتأكد من السياسة المعتمدة.
• "تسجيل الخروج من Element يُسجّل خروجي من كل مكان." يمكن أن تبقى جلسات المتصفح نشطة على Keycloak. قم بتكوين واختبار تسجيل الخروج عبر القناة الخلفية إذا لزم إنهاء الجلسة مركزياً.

قائمة التحقق من الصحة

• يستخدم عميل Keycloak تدفق رمز التفويض، ومصادقة العميل، ووظيفة الاستدعاء الدقيقة لـ Synapse أو MAS.
• يتطابق عنوان URL الخاص بالجهة المصدرة مع بيانات التعريف الخاصة باكتشاف المجال، ويتم تخزين سر العميل على جانب الخادم.
• يبدأ برنامج Synapse أو MAS بدون أخطاء في تكوين OIDC ويعرض طريقة تسجيل الدخول المقصودة.
• يمكن للمستخدم التجريبي تسجيل الدخول من جلسة متصفح جديدة، والوصول إلى حساب Matrix المتوقع، وإكمال جلسة Element عادية.
• سلوك تسجيل الخروج، والحسابات الحالية، وقيود التسجيل، وأي وصول احتياطي للمسؤول يتوافق مع سياستك.

المراجع الرسمية

• دليل استخدام Synapse v1.144 OpenID Connect، بما في ذلك إعدادات عميل Keycloak وردود الاتصال.
• إعدادات Element Web: خيارات إعادة توجيه تسجيل الدخول الموحد
• خدمة مصادقة المصفوفة: تهيئة موفر تسجيل الدخول الموحد (SSO) في المصدر
• دليل إدارة خادم Keycloak 26.8.0