---
type: how-to
title: Keycloak
summary: "Gerbangi login, reset kata sandi, dan registrasi Keycloak dengan Caputchin: pasang extension-nya, pilih mode render, dan verifikasi token di sisi server."
---

Keycloak adalah sebuah server, bukan halaman tempat kamu menyematkan skrip, jadi Caputchin hadir sebagai sebuah **extension** Keycloak: sebuah JAR provider yang kamu jatuhkan ke dalam Keycloak. Ia merender widget Caputchin di halaman login, reset kata sandi, dan registrasi, lalu memverifikasi token dari dalam Keycloak sebelum alurnya berlanjut. Baik widget checkbox maupun game-nya sama-sama jalan.

Extension-nya bersumber terbuka. Referensi lengkapnya (setiap properti konfigurasi, JSON ekspor realm, kontrak theme, dan matriks kompatibilitas) hidup di repositori: [github.com/Caputchin/caputchin-keycloak](https://github.com/Caputchin/caputchin-keycloak).

<Callout type="info">
Jalan dengan Keycloak 26.x (distribusi Quarkus). Kamu butuh akses ke deployment Keycloak untuk menambahkan JAR provider dan menjalankan `kc.sh build`; ini bukan aplikasi marketplace terhosting.
</Callout>

## 1. Pasang extension-nya

Bangun JAR provider dan taruh di Keycloak, lalu bangun ulang:

```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` wajib agar Keycloak menemukan provider-providernya.

## 2. Pilih cara widget merender

Ada dua cara, dan kamu memilih per realm.

### Siap pakai: theme bawaan (tanpa theme kustom)

JAR-nya membawa sebuah theme login `caputchin`. Setel di **Realm Settings → Themes → Login theme: `caputchin`**, dan widget merender di halaman login, reset, dan registrasi tanpa menyunting template. Ini jalur tercepat kalau kamu memakai login Keycloak standar.

### Headless: theme-mu sendiri yang merender widget

Kalau kamu mengirim theme login kustom (misalnya theme React Keycloakify), pertahankan theme-mu dan jalankan extension secara headless. Ia membuka konfigurasi widget ke konteks halaman dan memvalidasi token; theme-mu merender elemen `<caputchin-widget>` (atau `<caputchin-game>`) dan menatanya dengan design token-mu. Field token-nya adalah `caputchin-token`. Kontrak atribut lengkap dan sebuah contoh Keycloakify ada di [panduan theme repositori](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).

## 3. Ikat ke alurmu

Di **Authentication → Flows**, gandakan alur yang ingin kamu lindungi dan tukar eksekusinya:

| Alur | Setel eksekusi ke |
| --- | --- |
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | tambahkan Caputchin ke formulir registrasi |

Tantangan login dan reset merender di halaman yang sama dengan kredensial, bukan sebagai langkah terpisah. Buka konfigurasi tiap eksekusi (roda giginya) untuk menyetel kunci-kuncimu. Jangan menambahkan tantangan ke alur direct grant: di sana tak ada peramban, jadi itu akan merusak permintaan token via API.

## 4. Konfigurasikan kuncinya

Di konfigurasi eksekusi, setel:

- **Kunci situs**: public key-mu (`cpt_pub_...`). Satu-satunya nilai yang dikirim ke peramban.
- **Kunci rahasia**: secret-mu (`cpt_sec_...`). Kamu bisa menyimpannya sebagai literal, mengarahkan ke variabel lingkungan (agar tak pernah masuk ke ekspor realm-mu), atau memakai referensi `${vault.*}`.
- **Mode widget**: `checkbox`, `invisible`, atau `game`. Plus ukuran, locale (default mengikuti locale realm), dan skin.
- **Fail closed**: menyala secara baku, jadi gangguan verifikasi memblokir alih-alih membiarkan bot lewat.

Tampilan yang lebih kaya (game mana, skin, merek) disetel sekali saja di [dasbor Caputchin](https://caputchin.com) pada kunci situs itu sendiri, jadi kamu tak mengulanginya di sini.

## 5. Izinkan widget di Content Security Policy-mu

CSP login bawaan Keycloak lebih ketat dari yang widget butuhkan. Di **Realm Settings → Security Defenses → Content Security Policy**, izinkan skrip loader, host verifikasi, dan WebAssembly. Nilai persisnya ada di [panduan CSP repositori](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).

<Callout type="info">
Verifikasi di sisi server (Keycloak ke host verifikasi) adalah panggilan server-ke-server dan tak terpengaruh CSP peramban. Hanya lalu lintas widget di sisi peramban yang terpengaruh.
</Callout>

## Coba secara lokal

Repositori menyertakan sebuah Keycloak lokal satu perintah (`e2e/`) yang terhubung ke stack Caputchin lokal, agar kamu bisa mengeklik ketiga alur tergerbang sebelum men-deploy. Lihat [README repositori](https://github.com/Caputchin/caputchin-keycloak).