ربط Element Web بـ Keycloak عبر Synapse OIDC

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

مثال توضيحي (افتراضي): تقوم مؤسسة صغيرة بتشغيل Element Web على العنوان chat.example.org، وSynapse على العنوان matrix.example.org، وKeycloak على العنوان login.example.org. ينطبق التسلسل نفسه على أسماء المضيفين الأخرى، ولكن يجب أن يتطابق كل عنوان URL مع إعداداتك العامة الفعلية. هذا المثال توضيحي فقط، وليس تقريرًا عن إعداد فعلي.

ما تحتاج إليه قبل تغيير الإعدادات

استخدم عناوين URL عامة بتقنية HTTPS لكل من Keycloak وSynapse. تتطلب وثائق OIDC الخاصة بـ Synapse وجود مصدر آمن لموفر الهوية، ويجب أن يكون رد الاتصال الخاص به قابلاً للوصول إليه عبر عنوان URL العام الخاص بـ Synapse. تأكد من اسم النطاق في Keycloak وSynapse public_baseurl، وعنوان URL للخادم الرئيسي المُقدَّم إلى Element Web. في حال وجود خادم وكيل عكسي أمام أيٍّ من الخدمتين، يجب عليه توجيه الطلبات إلى الواجهة الخلفية الصحيحة مع الحفاظ على مُضيف HTTPS الخارجي ونظامه.

يستخدم نظام Synapse الحالي oidc_providersقائمة. أما نموذج الموفر الواحد القديم oidc_configفقد أصبح مهملاً. احتفظ بحساب مدير النظام ونسخة من الإعدادات الحالية أثناء الاختبار. لا تُعطّل تسجيل الدخول بكلمة المرور أو التسجيل حتى تتأكد من آلية تسجيل الدخول الموحد (SSO) وتُحدد كيفية إنشاء الحسابات.

1. قم بتسجيل Synapse كعميل في Keycloak

في بيئة Keycloak حيث يتواجد مستخدمو مؤسستك، أنشئ عميل OpenID Connect لـ Synapse. يستخدم مثال Keycloak الرسمي لـ Synapse عميلًا سريًا بمعرّف عميل synapse. عيّن عنوان URI لإعادة التوجيه الصحيح إلى هذا المعرّف، مع استبدال اسم مضيف Synapse الخاص بك.

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

في الإعداد الافتراضي، اضبط نوع وصول العميل على "سري" وقم بتمكين العميل. في علامة تبويب "بيانات الاعتماد"، انسخ سر العميل المُنشأ إلى نظام إدارة الأسرار الخاص بك؛ لا تضعه في قسم "عام" في Element Web config.jsonأو تنشره في أي مستودع.

يُعدّ عنوان إعادة التوجيه (URI) مصدرًا شائعًا للفشل. يجب أن يستخدم عنوان URL العام لـ Synapse، /_synapse/client/oidc/callbackوالمسار الدقيق، ونفس المخطط واسم المضيف اللذين يراهما Synapse من المتصفح. تجنّب استخدام عنوان عام (wildcard) عند استخدام عنوان URI دقيق. إذا قمت لاحقًا بتفعيل تسجيل الخروج عبر القناة الخلفية، فأضف نقطة نهاية القناة الخلفية الموثقة لـ Synapse في Keycloak أيضًا؛ هذا اختياري ومنفصل عن تسجيل الدخول الأساسي.

2. أضف موفر Keycloak إلى Synapse

عدّل الملف النشط homeserver.yaml. استبدل اسم النطاق والسر أدناه بقيمك، وتأكد من عنوان URL الخاص بالمُصدر من مستند اكتشاف OpenID الخاص بالنطاق. يكون شكل مُصدر نطاق Keycloak القياسي على النحو التالي:

https://login.example.org/realms/your-realm

بالنسبة لعملية نشر تستخدم نقطة نهاية الاكتشاف القياسية والمطالبات الموضحة في مثال Keycloak الخاص بـ Synapse، يكون إدخال الموفر كما يلي:

oidc_providers:
  - idp_id: keycloak
    idp_name: "Company Login"
    issuer: "https://login.example.org/realms/your-realm"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
    scopes: ["openid", "profile"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

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

احتفظ بالقائمة الحالية oidc_providersإذا تم تكوين موفري هوية آخرين؛ أضف هذا الإدخال بدلاً من استبدال الموفرين غير ذوي الصلة. احمِ سر العميل كسر، واضبط أذونات الملفات وفقًا لبيئة النشر الخاصة بك. تحقق من صحة مسافة YAML البادئة، ثم أعد تشغيل Synapse باستخدام إجراء الخدمة أو الحاوية الخاص بتثبيتك. قد تتضمن عمليات التثبيت المعبأة بالفعل تبعيات OIDC؛ بالنسبة لتثبيت بيئة افتراضية، توثق Synapse عملية التثبيت matrix-synapse[oidc]. اتبع إرشادات مسؤول حزمة التثبيت الخاصة بك لطرق التثبيت الأخرى.

3. توجيه عنصر الويب إلى نفس الخادم الرئيسي

يجب أن يتعرف Element Web config.jsonعلى خادم Synapse كخادم رئيسي له، على سبيل المثال من خلال [رابط غير واضح] default_server_config.mHomeserver.base_url. استخدم عنوان URL الخاص بالخادم الرئيسي، وليس عنوان Keycloak. Element Web هو عميل ثابت: أعد نشره أو أعد تحميل إعداداته باستخدام طريقة الاستضافة الخاصة بك بعد تغيير عنوان URL الخاص بالخادم الرئيسي. لا تضع سر عميل Keycloak في هذا الملف لأن المتصفحات يمكنها قراءته.

في المثال الافتراضي، يتم استضافة Element Web على خادم https://chat.example.orgويتصل بخادم آخر https://matrix.example.org. عندما يختار المستخدم خيار تسجيل الدخول الموحد (SSO) على شاشة تسجيل الدخول في Element، يجب أن ينتقل المتصفح عبر مسار تسجيل الدخول في Synapse إلى نطاق Keycloak ثم يعود إلى رد اتصال Synapse. قد تختلف صياغة الأزرار وتصميم شاشة تسجيل الدخول باختلاف إصدار Element Web وإعدادات الخادم؛ لذا يُنصح باختبار السلوك بدلاً من الاعتماد على تسمية محددة.

4. اختبر باستخدام حساب واحد قبل تطبيق ميزة تسجيل الدخول الموحد (SSO).

افتح Element Web في نافذة متصفح خاصة، ثم اختر خيار تسجيل الدخول الموحد (SSO). سجّل الدخول باستخدام حساب Keycloak تجريبي، ووافق على طلب الوصول إذا طُلب منك ذلك، وتأكد من عودة المتصفح إلى الخادم الرئيسي المقصود وفتح حساب Matrix المتوقع. تحقق من أن معرّف Matrix الناتج يحتوي على الجزء المحلي المطلوب. راجع سجلات Synapse وKeycloak إذا أظهر المتصفح خطأً.

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

تسجيل الخروج الاختياري: يدعم Synapse تسجيل الخروج عبر قناة OIDC الخلفية. لاستخدامه، قم بتعيينه backchannel_logout_enabled: trueضمن هذا الموفر وقم بتكوين عنوان URL لتسجيل الخروج عبر قناة Keycloak الخلفية https://matrix.example.org/_synapse/client/oidc/backchannel_logout. كما توثق Synapse تفعيل خيار "الجلسة مطلوبة" في Keycloak. يعالج هذا الخيار إشعارات تسجيل الخروج التي يبدأها الموفر؛ وهو غير مطلوب لتفعيل تسجيل الدخول الموحد الأولي.

قبل بدء التشغيل: حدد ما إذا كان يجب على نظام تسجيل الدخول الموحد (SSO) إنشاء مستخدمين جدد في Matrix أو مصادقة الحسابات التي تُنشئها بشكل منفصل فقط، ثم راجع خيارات OIDC الخاصة بـ Synapse للإصدار المُثبّت لديك. قد تتغير تسميات التكوين وواجهة إدارة Keycloak بين الإصدارات. تتبع الخطوات المذكورة هنا وثائق OIDC الخاصة بـ Synapse والمتاحة في 10 أكتوبر 2026، وتفترض وجود نطاق Keycloak قياسي ونشر Synapse باستخدام تنسيق الموفر الموثق. راجع دليل Synapse OpenID Connect وKeycloak ، ومرجع تكوين Synapse ، ووثائق Keycloak الرسمية قبل تطبيق الإعدادات الخاصة بالإصدار. بمجرد تسجيل دخول حساب الاختبار بنجاح وتوفير مسار استرداد، وثّق عملية رد الاتصال النهائية، والجهة المُصدرة، وتعيين المطالبات للمسؤولين.

اترك تعليقاً

اجعل خادم Matrix Synapse الخاص بك قابلاً للوصول إليه من أجل الاتحاد

اجعل خادم Matrix Synapse الخاص بك قابلاً للوصول إليه من أجل الاتحاد

قم بتكوين اكتشاف Synapse و HTTPS وتوجيه الوكيل حتى تتمكن خوادم Matrix المنزلية الأخرى من العثور على خادمك والاتصال به.

ربط Element Web بـ Keycloak عبر Synapse OIDC

قم بتكوين عميل Keycloak OIDC وموفر Synapse حتى يتمكن مستخدمو Element Web من تسجيل الدخول من خلال خادم الهوية الخاص بك دون الكشف عن أسرار العميل.

إعداد النسخ الاحتياطي لمفتاح العنصر والتوقيع المتبادل بأمان

إعداد النسخ الاحتياطي لمفتاح العنصر والتوقيع المتبادل بأمان

احفظ مفتاح الاسترداد، وتحقق من جلسات Element الخاصة بك، وتأكد من إمكانية استعادة مفاتيح الرسائل المشفرة دون الخلط بين النسخة الاحتياطية وكلمة مرور حسابك.

إيقاف أعطال ذاكرة Matrix Synapse أثناء مزامنة العميل

تشخيص حالات فشل نفاد الذاكرة في Synapse أثناء المزامنة، وضبط التخزين المؤقت بأمان، وتحديد تراكم الطلبات، والتحقق من استخدام الذاكرة بشكل مستقر.

حل أخطاء شهادة TLS الخاصة باتحاد Synapse

تتبع حالات فشل شهادات اتحاد المصفوفة إلى الخادم الصحيح، وإصلاح سلسلة TLS أو ثقة CA، والتحقق من الإصلاح دون تعطيل عمليات التحقق الأمني.

ضع خادم Synapse Matrix خلف Cloudflare بأمان

ضع خادم Synapse Matrix خلف Cloudflare بأمان

توجيه عملاء Matrix والاتحاد عبر Cloudflare على HTTPS 443، والحفاظ على اكتشاف Synapse، وتجنب تخزين حركة مرور API مؤقتًا أو تعطيل عمليات تحميل الوسائط.

استعادة برنامج Matrix Synapse بأمان باستخدام نسخة احتياطية من قاعدة بيانات PostgreSQL

قم بعمل نسخة احتياطية من Synapse باستخدام pg_dump، وقم بحماية مفتاح التوقيع والوسائط الخاصة به، واستعدها في قاعدة بيانات PostgreSQL نظيفة دون إعادة استخدام المفاتيح القديمة التي تستخدم لمرة واحدة.

قم بتشغيل Mjölnir كبوت لإدارة غرف المصفوفة باستخدام Docker

قم بتشغيل Mjölnir كبوت لإدارة غرف المصفوفة باستخدام Docker

قم بإعداد Mjölnir باستخدام حساب Matrix مخصص، وغرفة إدارة مشفرة، وDocker Compose، وقائمة السياسات، وفحوصات الأذونات.

تفعيل خاصية مزامنة انزلاق المصفوفة الأصلية لتحميل أسرع على الأجهزة المحمولة

تفعيل خاصية مزامنة انزلاق المصفوفة الأصلية لتحميل أسرع على الأجهزة المحمولة

تجاوز استخدام الخادم الوكيل القديم وقم بتكوين ميزة المزامنة المنزلقة المدمجة في Synapse. تحقق من اكتشاف العميل، ثم قم بقياس تحميل قائمة الغرف وسلوك إعادة الاتصال على هاتف متوافق.

استضافة موقع Element Web على خادم Nginx مع خادم منزلي مخصص

قم بنشر Element Web كموقع ثابت، وقم بتوجيهه إلى خادم Matrix الرئيسي الخاص بك، وأضف HTTPS، وقم بتكوين Nginx لتقديم التحديثات بدون ملفات قديمة.