Keycloak

Keycloak خادم، لا صفحة تضمّن فيها سكربتًا، لذا يأتي Caputchin بوصفه إضافة لـ Keycloak: ملف JAR لمزوّد تضيفه إلى Keycloak. يعرض أداة Caputchin على صفحات تسجيل الدخول وإعادة تعيين كلمة المرور والتسجيل، ويتحقّق من الرمز من داخل Keycloak قبل أن يمضي التدفّق قُدُمًا. تعمل كلٌّ من أداة خانة الاختيار واللعبة.

الإضافة مفتوحة المصدر. المرجع الكامل (كل خاصيّة إعداد، وملف JSON لتصدير الـ realm، وعقد الـ theme، ومصفوفة توافق) موجود في المستودع: github.com/Caputchin/caputchin-keycloak. احسب نحو 15 دقيقة من حساب جديد حتى أول جلسة متحقَّق منها على الخادم.

1. أنشئ مفتاح موقع

سجّل الدخول على caputchin.com/login (أول تسجيل دخول يُنشئ الحساب)، وافتح الفريق شخصي، وانقر إنشاء مفتاح موقع، وسمّه باسم الـ realm في Keycloak، ثم انقر إنشاء. انسخ القيمتين كلتيهما:

• المفتاح العام (cpt_pub_...)،
• السرّ (cpt_sec_...). لا يُعرَض إلا مرة واحدة.

ويمرّ بك أنشئ حسابك وأول مفتاح موقع على الشاشات نفسها بتفصيل أكبر.

2. ثبّت الإضافة

نزّل caputchin-keycloak.jar من أحدث إصدار، وانسخه إلى مجلد providers/ في Keycloak، ثم أعد البناء:

cp caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimized

kc.sh build ضروري كي يكتشف Keycloak المزوّدين. وفي صورة حاوية، انسخ ملف JAR وشغّل البناء داخل الصورة:

FROM quay.io/keycloak/keycloak:26.4
COPY caputchin-keycloak.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

ولبناء ملف JAR من المصدر بدلًا من ذلك، انظر دليل التثبيت في المستودع.

3. سلّم السرّ إلى Keycloak

أبقِ السرّ خارج إعداد الـ realm: اضبطه متغيّرَ بيئة على خادم Keycloak، مثلًا CAPUTCHIN_SECRET، ثم أعد تشغيل Keycloak. في الخطوة 5 لا تُدخل سوى اسم المتغيّر. ويصلح أيضًا سرّ حرفي أو مرجع ${vault.*}؛ انظر دليل الإعداد في المستودع.

4. اختر كيف تُعرَض الأداة

ثمّة طريقتان، وتختار لكل realm.

جاهز للتشغيل: الـ theme المُرفق

يأتي ملف JAR مع theme تسجيل دخول اسمه caputchin. في Admin Console، افتح الـ realm الخاص بك، واذهب إلى Realm settings → Themes، واضبط Login theme على caputchin، ثم انقر Save. تُعرَض الأداة على صفحات تسجيل الدخول وإعادة التعيين والتسجيل بلا تحرير قوالب. هذا أسرع مسار إن كنت تستخدم تسجيل دخول Keycloak القياسي.

بلا رأس: الـ theme الخاص بك يعرض الأداة

إن كنت تقدّم theme تسجيل دخول مخصّصًا (مثلًا theme بـ React من Keycloakify)، فأبقِ على الـ theme الخاص بك وشغّل الإضافة بلا رأس. تكشف إعداد الأداة في سياق الصفحة وتتحقّق من صحة الرمز؛ ويعرض الـ theme الخاص بك عنصر <caputchin-widget> (أو <caputchin-game>). حقل الرمز هو caputchin-token. عقد السمات الكامل ومثال Keycloakify في دليل الـ theme في المستودع.

5. اربطها بتدفّق تسجيل الدخول

لا يغيّر Keycloak الـ authenticator الخاص بخطوة في مكانها، لذا تضيف خطوة Caputchin إلى نسخة من التدفّق وتحذف الخطوة الأصلية.

1. اذهب إلى Authentication. على تدفّق browser، افتح القائمة (⋮)، وانقر Duplicate، وسمِّ النسخة (مثلًا browser caputchin)، ثم انقر Duplicate.

2. في النسخة، اعثر على التدفّق الفرعي forms. انقر زرّ + (Add) الخاص به، واختر Add execution، وحدّد Caputchin Username Password Form، ثم انقر Add.

3. اسحب الخطوة الجديدة إلى أعلى التدفّق الفرعي forms، فوق التدفّق الفرعي Conditional 2FA، كي تعمل حيث كانت الخطوة القديمة تعمل. متطلّبها هو Required.

4. احذف خطوة Username Password Form الأصلية من التدفّق الفرعي forms.

5. انقر الترس (Settings) على خطوة Caputchin واملأ:

   • Alias: أي اسم، مثل caputchin-login.
   • Site key: مفتاحك العام (cpt_pub_...)، وهو القيمة الوحيدة المُرسَلة إلى المتصفّح.
   • Secret key env var: اسم المتغيّر من الخطوة 3، مثل CAPUTCHIN_SECRET.

   ثم انقر Save. للحقول الأخرى قيم افتراضية صالحة: Widget mode على checkbox (أو invisible، أو game)، وLocale على kc (يتبع لغة الـ realm)، وFail closed مفعّل، فانقطاع التحقّق يحجب عمليات تسجيل الدخول بدل أن يتركها تمرّ.

6. افتح قائمة Action الخاصة بالتدفّق، وانقر Bind flow، وأبقِ Browser flow، ثم انقر Save.

يُعرَض التحدّي على الصفحة نفسها مع بيانات الاعتماد، لا كخطوة منفصلة. ومع الإعدادات الافتراضية، يجري الفحص حين ينقر المستخدم Sign In.

إعادة تعيين كلمة المرور والتسجيل

النمط نفسه يحمي النموذجين الآخرين:

لكل خطوة Caputchin إعداداتها الخاصة (الترس)، فأدخل مفتاح الموقع ومتغيّر السرّ في كلٍّ منها. لا تضف تحدّيًا إلى تدفّق direct grant: لا متصفّح هناك، فسيكسر ذلك طلبات الرموز عبر الـ API. ويعرض الربط بالتدفّقات في المستودع الإعداد نفسه بصيغة JSON لتصدير الـ realm.

المظهر الأغنى (أيّ لعبة، والمظاهر، والعلامة) يُضبط مرة واحدة في لوحة تحكّم Caputchin على مفتاح الموقع نفسه، فلا تكرّره في Keycloak.

6. افحص Content Security Policy

Content Security Policy الافتراضية لتسجيل الدخول في Keycloak (تحت Realm settings → Security defenses → Headers) هي frame-src 'self'; frame-ancestors 'self'; object-src 'none';. إنها تقيّد الإطارات، لا السكربتات ولا الاتصالات، واللعبة تعمل في إطار srcdoc، لذا تعمل معها خانة الاختيار والأداة غير المرئية واللعبة جميعًا دون أي تغيير.

إن ضبطت سياسة أشدّ من عندك، فابدأ من السياسة الموجودة في دليل الـ CSP في المستودع. توجيه script-src ينطبق أيضًا على السكربتات المضمّنة الخاصة بـ Keycloak نفسه، فاختبر صفحة تسجيل الدخول و Account Console بعد أي تغيير.

التحقّق على جانب الخادم (من Keycloak إلى مضيف التحقّق) نداء من خادم إلى خادم، ولا تؤثّر فيه سياسة المتصفّح.

7. أكّد أول جلسة متحقَّق منها على الخادم

1. افتح صفحة تسجيل الدخول في تطبيقك (أو صفحة تسجيل الدخول للـ realm) في نافذة خاصة.
2. سجّل الدخول بمستخدم تجريبي. تعمل الأداة حين تنقر Sign In، ويُدخلك Keycloak.
3. في لوحة تحكّم Caputchin، افتح فريقك وانقر مفتاح موقعك. حدّث الإحصاءات.

تعرض المُتحقَّق منها على الخادم الآن 1 على الأقل: أكّد Keycloak رمزًا مع Caputchin. هذه أول جلسة متحقَّق منها لديك. وإن عرضت صفحة تسجيل الدخول "Verification failed. Please complete the check and try again." (أو "فشل التحقق. يرجى إكمال الفحص والمحاولة مرة أخرى." في realm لغته العربية) وبقيت المُتحقَّق منها على الخادم عند 0، فالرمز لم يصل إلى Keycloak قط: ابحث في وحدة تحكّم المتصفّح عن خطأ Content Security Policy (الخطوة 6). وإن ارتفعت المُكمَّلة على العميل وظلّ تسجيل الدخول يفشل، فتأكّد أن متغيّر السرّ من الخطوة 3 مضبوط على الخادم. ويشرح الإحصاءات والجلسات كل رقم.

جرّبها محليًّا

يتضمّن المستودع نسخة Keycloak محلية بأمر واحد (e2e/) موصولة بحزمة Caputchin محلية، كي تنقر عبر التدفّقات الثلاثة المحكومة جميعها قبل النشر. انظر README المستودع.

انظر أيضًا

• نظرة عامة على مفاتيح المواقع
• WordPress