Keycloak

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

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

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

ابنِ ملف JAR للمزوّد وضعه في Keycloak، ثم أعد البناء:

# build (no JDK on the host? run it in Docker)
docker run --rm -v "$PWD":/work -w /work maven:3.9-eclipse-temurin-21 mvn -DskipTests package

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

‏kc.sh build ضروري كي يكتشف Keycloak المزوّدين.

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

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

جاهز للتشغيل: الـ theme المُرفق (بلا theme مخصّص)

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

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

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

3. اربطها بتدفّقاتك

في Authentication → Flows، انسخ التدفّق الذي تريد حمايته وبدّل الـ execution:

يُعرَض تحدّيا تسجيل الدخول وإعادة التعيين على الصفحة نفسها مع بيانات الاعتماد، لا كخطوة منفصلة. افتح إعداد كل execution (الترس) كي تضبط مفاتيحك. لا تضف تحدّيًا إلى تدفّق direct grant: لا متصفّح هناك، فسيكسر ذلك طلبات الرموز عبر الـ API.

4. اضبط المفاتيح

في إعداد الـ execution، اضبط:

• مفتاح الموقع: مفتاحك العام (cpt_pub_...). القيمة الوحيدة المُرسَلة إلى المتصفّح.
• المفتاح السرّي: سرّك (cpt_sec_...). تستطيع تخزينه كقيمة حرفية، أو توجيهه إلى متغيّر بيئة (كي لا يقع أبدًا في تصدير الـ realm خاصتك)، أو استخدام مرجع ${vault.*}.
• وضع الأداة: checkbox، أو invisible، أو game. إضافةً إلى الحجم، واللغة (تتبع لغة الـ realm افتراضيًّا)، والمظهر.
• الإغلاق عند الفشل: مفعّل افتراضيًّا، فانقطاع التحقّق يحجب بدل أن يترك البوتات تمرّ.

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

5. اسمح بالأداة في Content Security Policy خاصتك

‏CSP تسجيل الدخول الافتراضية في Keycloak أكثر صرامةً مما تحتاج إليه الأداة. تحت Realm Settings → Security Defenses → Content Security Policy، اسمح بسكربت المُحمِّل، ومضيف التحقّق، وWebAssembly. القيمة الدقيقة في دليل الـ CSP بالمستودع.

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

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