---
type: how-to
title: Keycloak
summary: "احكم تسجيل دخول Keycloak وإعادة تعيين كلمة المرور والتسجيل ببوّابة Caputchin: ثبّت الإضافة، واختر وضع عرض، وتحقّق من الرمز على جانب الخادم."
---

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

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

<Callout type="info">
يعمل مع Keycloak 26.x (توزيعة Quarkus). تحتاج إلى وصول إلى نشر Keycloak كي تضيف ملف JAR لمزوّد وتشغّل `kc.sh build`؛ هذا ليس تطبيق متجر مُستضافًا.
</Callout>

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

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

```bash
# 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 بالمستودع](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).

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

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

| التدفّق | اضبط الـ execution على |
| --- | --- |
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | أضف Caputchin إلى نموذج التسجيل |

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

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

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

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

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

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

‏CSP تسجيل الدخول الافتراضية في Keycloak أكثر صرامةً مما تحتاج إليه الأداة. تحت **Realm Settings → Security Defenses → Content Security Policy**، اسمح بسكربت المُحمِّل، ومضيف التحقّق، وWebAssembly. القيمة الدقيقة في [دليل الـ CSP بالمستودع](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).

<Callout type="info">
التحقّق على جانب الخادم (من Keycloak إلى مضيف التحقّق) نداء من خادم إلى خادم، ولا تؤثّر فيه CSP المتصفّح. لا يتأثّر بها إلا حركة الأداة على جانب المتصفّح.
</Callout>

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

يتضمّن المستودع نسخة Keycloak محلية بأمر واحد (`e2e/`) موصولة بحزمة Caputchin محلية، كي تنقر عبر التدفّقات الثلاثة المحكومة جميعها قبل النشر. انظر [README المستودع](https://github.com/Caputchin/caputchin-keycloak).