كيفية تهيئة Keycloak كموفر هوية (IDP) لخدمة ownCloud Infinite Scale

يربط هذا الدليل منصة ownCloud Infinite Scale (oCIS) بمنصة Keycloak باستخدام OpenID Connect (OIDC)، وهي طبقة الهوية المبنية على بروتوكول OAuth 2.0. تتولى Keycloak مهمة مصادقة المستخدمين، بينما تثق oCIS في الهوية الموقعة ومعلومات الوصول التي تصدرها Keycloak. يستخدم تسجيل الدخول عبر المتصفح عمليات إعادة توجيه HTTPS، كما تحتاج oCIS أيضًا إلى الوصول إلى نقاط نهاية اكتشاف Keycloak ومفتاح التوقيع.

اعتبارًا من 6 أكتوبر 2026، تصف وثائق إدارة ownCloud الحالية هذه الإعدادات ضمن Infinite Scale 9.0. يُعد مثال نشر Keycloak الرسمي نقطة انطلاق مفيدة، ولكن قد يتغير ملف Compose الخاص به وتصدير النطاق. لذا، يُنصح بتثبيت إصدارات الصور المتوافقة ومراجعة الملفات التي تنشرها بدلًا من نسخ مثال غير مُدار بشكل أعمى.

ما تحتاجه قبل تهيئة OIDC

قم بإعداد عنوان HTTPS العام لـ oCIS، مثل ` https://cloud.example.com/cd https://sso.example.com...

• نشر ownCloud Infinite Scale يعمل بشكل صحيح، بالإضافة إلى إمكانية وصول المسؤول إلى بيئته أو تكوين Compose الخاص به.
• نطاق Keycloak عامل وصلاحيات وصول إدارية. النطاق هو مساحة اسم Keycloak للمستخدمين والعملاء والأدوار وإعدادات الهوية.
• شهادة TLS موثوقة من قِبل المتصفح والخادم الذي يتحقق من صحة شهادة TLS الخاصة بـ Keycloak. لا ينبغي تعطيل التحقق من الشهادة في بيئة الإنتاج.
• قرار بشأن مطابقة الحسابات: ربط مستخدمي oCIS الحاليين بمطالبات هوية ثابتة، أو تمكين توفير حساب تسجيل الدخول الأول مع الواجهة الخلفية للمستخدم التي تم تمكين الكتابة لها.

1. ابحث عن جهة إصدار Keycloak المحددة

في Keycloak، يكون مُصدر OIDC عادةً هو عنوان URL الخاص بالنطاق، وليس عنوان URL الخاص بلوحة تحكم المسؤول أو عنوان URL الخاص بمستند الاكتشاف. بالنسبة لنطاق باسم معين team، قد يبدو كالتالي https://sso.example.com/realms/team: . قد تختلف عمليات التثبيت أو النشر القديمة التي تستخدم بادئة مسار، لذا لا تقم بإنشاء القيمة من الذاكرة. افتح مستند اكتشاف النطاق في المسار المحدد https://sso.example.com/realms/team/.well-known/openid-configurationوانسخ قيمة الخاصية issuerبدقة.

من خادم يمكنه الوصول إلى Keycloak، يمكنك فحص المستند باستخدام:

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

تأكد من أن جهة الإصدار المُسترجعة تستخدم نفس المخطط والمضيف والمسار واسم النطاق الذي ستُهيئه في oCIS. يتحقق OpenID Connect من هوية جهة الإصدار بدقة؛ وقد يؤدي عدم تطابق اسم مضيف الخادم الوكيل العكسي أو وجود شرطة مائلة زائدة إلى تعطيل تسجيل الدخول.

2. تسجيل عميل OIDC لـ ownCloud Web

العميل هو تطبيق تسجيل الدخول الذي يستخدمه Keycloak لتحديد الخدمة التي يمكنها طلب تسجيل الدخول. أنشئ أو عدّل عميل OpenID Connect في النطاق المستخدم لـ oCIS. استخدم معرّف عميل مثل `<اسم العميل>` webأو قيمة مخصصة، وتأكد من مطابقته للقيمة WEB_OIDC_CLIENT_IDفي oCIS. يستخدم مثال ownCloud الرسمي `<اسم العميل>` webكقيمة افتراضية.

بالنسبة للعميل المستند إلى المتصفح، استخدم آلية رمز التفويض القياسية وتكوين العميل العام المتوافق مع نطاق المثال الرسمي. أدخل أنماط إعادة توجيه HTTPS وإعادة التوجيه بعد تسجيل الخروج المطلوبة بدقة لتطبيقك. يُعدّ استخدام نمط اسم مضيف ضيق، مثل `<اسم المضيف>`، https://cloud.example.com/*أسهل في التدقيق من استخدام اسم مضيف عام واسع النطاق يشمل جميع المضيفين. أضف فقط أصول الويب التي يحتاجها تطبيقك. لا تُنشئ سر عميل لعميل متصفح عام ثم تُضمّنه في تكوين الواجهة الأمامية.

3. تحقق من الادعاءات والنطاقات

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

بالنسبة للحسابات الموجودة، يجب أن تتطابق بيانات التعريف المُكوّنة مع سمة المستخدم الثابتة المقابلة لها في ownCloud. قد يؤدي تغيير اسم المستخدم أو البريد الإلكتروني إلى مشاكل في مطابقة الحساب إذا كنت تستخدمه كمعرّف دائم. بيانات التعريف subمضمونة بأنها فريدة وثابتة لكل موفر هوية، ولكنها قد لا تتطابق مع اسم مستخدم موجود مسبقًا. اختبر مطابقة الحساب باستخدام حساب غير إداري قبل منح الوصول لجميع المستخدمين.

4. توجيه مقياس لانهائي إلى Keycloak

قم بتعيين القيم التالية في بيئة نشر oCIS. يفترض هذا المثال استخدام HTTPS ونطاق Keycloak على /realms/teamالرابط التالي. استخدم عناوين URL الخاصة بك. هذا الجزء المكتوب بنمط YAML هو مثال توضيحي؛ إذ تُعبّر طرق النشر الأخرى مثل Docker Compose وKubernetes وsystemd عن متغيرات البيئة بشكل مختلف.

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUERيختار موفر الهوية الخارجي. PROXY_OIDC_REWRITE_WELLKNOWN=trueيقوم الوكيل بإعادة كتابة نقطة نهاية اكتشاف OpenID Connect إلى جهة الإصدار المُكوّنة؛ وتوثّق ownCloud هذا كضرورة لعملاء سطح المكتب والهواتف المحمولة لاكتشاف الموفر. WEB_OIDC_CLIENT_IDيجب أن يتطابق مع عميل Keycloak. الاستثناء idpيتبع مثال Keycloak الخاص بـ ownCloud حتى لا يتم تشغيل الموفر المُضمّن كموفر تسجيل الدخول النشط.

إذا كنت ترغب في أن يقوم نظام oCIS بإنشاء حسابات عند تسجيل الدخول الناجح لأول مرة، فقم بإعداد PROXY_AUTOPROVISION_ACCOUNTS=trueخدمة Graph وتهيئتها باستخدام واجهة خلفية للمستخدم مع تمكين الكتابة. عيّن اسم المستخدم PROXY_USER_OIDC_CLAIMوقيمة PROXY_AUTOPROVISION_CLAIM_USERNAMEالخاصية إلى نفس المطالبات؛ بالنسبة لخاصية اسم المستخدم، راجع وثائق ownCloud PROXY_USER_CS3_CLAIM=usernameالخاصة بهذه العملية. التزويد التلقائي اختياري ويجب اختباره بشكل منفصل عن المصادقة. لا تقم بتفعيله إلا إذا كانت المطالبات الواردة فريدة ومُطابقة كما هو مُخطط لها.

5. السماح لموفر الهوية في سياسة أمان المحتوى

يستخدم Infinite Scale سياسة أمان المحتوى (CSP) للتحكم في المصادر الخارجية التي يمكن لعميل الويب الخاص به الاتصال بها. تشير وثائق ownCloud إلى أن موفر الهوية الخارجي، مثل Keycloak، يتطلب تعريفًا مناسبًا لسياسة أمان المحتوى. إذا ظهر زر تسجيل الدخول ولكن المتصفح يحظر الطلب، فتحقق من وحدة تحكم المتصفح بحثًا عن أخطاء سياسة أمان المحتوى. قم بتكوين السياسة من خلال ملف التكوين، PROXY_CSP_CONFIG_FILE_LOCATIONواسمح فقط بمصدر Keycloak والتوجيهات التي يحتاجها النشر. أعد تشغيل الخادم الوكيل أو النشر بعد تغيير الملف. لا تحل مشكلة الاتصال بالسماح لجميع المصادر.

6. أعد التشغيل وتحقق من التدفق الكامل

طبّق تغييرات البيئة وأعد تشغيل نشر oCIS باستخدام الطريقة التي تستخدمها لإدارته. لا يوجد أمر إعادة تشغيل موحد: فلكل من مشروع Compose وحمل عمل Kubernetes وخدمة systemd عناصر تحكم مختلفة. ثم تحقق من كل حلقة في سلسلة العمليات.

1. افتح عنوان URL لاكتشاف Keycloak وتأكد من أنه يُرجع JSON مع issuer، authorization_endpoint، token_endpoint، و jwks_uri.
2. افتح رابط موقع ownCloud الإلكتروني في نافذة متصفح خاصة. تأكد من إعادة توجيه المتصفح إلى نطاق Keycloak المتوقع.
3. قم بتسجيل الدخول باستخدام حساب تجريبي وتأكد من أن المتصفح يعود إلى نفس اسم مضيف ownCloud بدون حلقة إعادة توجيه.
4. تأكد من ظهور المستخدم المقصود - وليس نسخة مكررة تم إنشاؤها حديثًا - في Infinite Scale، وأن بإمكانه الوصول فقط إلى الموارد المتوقعة.
5. اختبر تسجيل الخروج، ثم كرر العملية باستخدام حساب ثانٍ. إذا كانت تطبيقات سطح المكتب أو تطبيقات الهاتف المحمول مشمولة، فاختبر اكتشافها وتسجيل الدخول إليها بشكل منفصل.

الإخفاقات الشائعة ومعانيها المعتادة

قائمة التحقق من الإنتاج

• تم اختبار إصدارات ownCloud و Keycloak باستخدام الدبوس بدلاً من الاعتماد على latestعلامة عائمة.
• استخدم بروتوكول HTTPS لكل من الخدمات العامة وحافظ على التحقق من الشهادات. تُوثّق منصة ownCloud تجاوز بروتوكول TLS غير الآمن باعتباره غير مناسب للإنتاج.
• حماية بيانات اعتماد مسؤول Keycloak، ونسخ قاعدة بيانات Keycloak وتكوين المجال احتياطيًا، وتقييد الوصول الإداري إلى Keycloak.
• يجب أن تقتصر عناوين إعادة التوجيه ومصادر الويب على أسماء مضيفي ownCloud الفعلية.
• قم بتوثيق مطالبة المعرف المختارة وعواقب تغيير أسماء المستخدمين أو أسماء النطاقات أو عناوين URL الخاصة بالجهة المصدرة أو معرفات العميل.
• اختبر إمكانية الوصول للاسترداد قبل تبديل نسخة الإنتاج، واحتفظ بنسخة احتياطية مخططة من التكوين السابق.

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

• تكوين خدمة الوكيل في ownCloud Infinite Scale 9.0
• دليل مثال لنشر keycloak على ownCloud
• ملفات نشر ownCloud ocis_keycloak الرسمية
• دليل إدارة خادم Keycloak 26.8
• جوانب الأمان في منصة ownCloud ذات النطاق اللامحدود