---
title: Keycloak
---

# Keycloak

Plugin Keycloak resmi CaptchaLa. Menambahkan tantangan CAPTCHA ke layar login, pendaftaran, dan reset password bawaan Keycloak, diverifikasi di sisi server, tanpa menulis kode apa pun. Dikirimkan sebagai satu provider JAR yang Anda letakkan ke dalam Keycloak.

## Cakupan

Setiap alur di bawah ini dihubungkan sebagai langkah autentikasi terpisah — Anda hanya melindungi layar yang diinginkan.

- Login browser (formulir username / password)
- Pendaftaran mandiri
- Reset password (layar "lupa password")

Tantangan ditampilkan sebagai widget mengambang secara default (`float`), atau sebagai modal klik-untuk-buka (`popup`).

## Instalasi

### 1. Dapatkan JAR

Plugin ini bersumber terbuka di
[**github.com/Captcha-La/captchala-keycloak**](https://github.com/Captcha-La/captchala-keycloak). Dua opsi:

- **Unduh rilis** (disarankan) — ambil `keycloak-captchala-<version>.jar` dari halaman Releases repositori.
- **Build dari sumber** — `git clone` repo lalu jalankan `mvn clean package`; JAR dihasilkan di bawah `target/`.

Plugin ini menargetkan Keycloak ≥ 26 (Quarkus) dan Java 17.

### 2. Deploy

```bash
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# restart Keycloak
```

Kemudian atur tema login: **Realm settings → Themes → Login theme → `captchala`**.

### 3. Dapatkan kunci Anda

Daftar di [`dash.captcha.la`](https://dash.captcha.la), buat aplikasi, lalu salin:

- **App Key** — kunci publik, disematkan di halaman
- **App Secret** — hanya sisi server, digunakan oleh Keycloak untuk mencetak token sekali pakai dan memanggil `/v1/validate`

### 4. Hubungkan alur

Di konsol admin, tambahkan eksekusi yang sesuai ke setiap alur yang ingin dilindungi, lalu klik ikon roda gigi untuk menempel **App Key** dan **App Secret** Anda:

- **Login browser** — duplikat alur *browser*, ganti **Username Password Form** dengan **Captchala Username Password Form** (REQUIRED), ikat sebagai alur browser realm.
- **Pendaftaran** — duplikat alur *registration*, tambahkan **Captchala Registration** (REQUIRED) ke sub-alur registration-form, ikat sebagai alur pendaftaran realm.
- **Reset password** — duplikat alur *reset credentials*, ganti **Choose User** dengan **Captchala Reset Credential (choose user)** (REQUIRED), ikat sebagai alur reset-credentials realm.

Buka salah satu layar yang dilindungi di jendela private untuk memastikan tantangan tampil dengan benar.

## Konfigurasi

Setiap eksekusi dikonfigurasi secara terpisah dari ikon roda giginya. Default sudah berfungsi langsung setelah kunci diatur.

| Pengaturan | Key | Default | Deskripsi |
| --- | --- | --- | --- |
| App Key | `app.key` | — | Kunci publik dari dasbor CaptchaLa. Wajib. |
| App Secret | `app.secret` | — | Rahasia server. Wajib. Disimpan tersamar, tidak pernah diekspos ke browser. |
| URL API dasar | `api.base` | `https://apiv1.captcha.la` | Base URL API CaptchaLa. |
| URL skrip widget | `script.url` | `https://api.captcha.la/sdk/jslib/captchala.js` | Lokasi pemuatan JS widget. |
| URL CSS widget | `css.url` | `https://api.captcha.la/sdk/jslib/captchala.css` | Lokasi pemuatan CSS widget. |
| Mode render | `product` | `float` | `float` (widget mengambang) atau `popup` (modal). |
| Label action | `action` | per alur | `action` yang dikirim saat validasi (`login`, `register`, `reset`). |
| Bahasa | `language` | lokal realm | Bahasa widget; kosong mengikuti lokal Keycloak. |
| Fail closed | `fail.closed` | `true` | Saat API CaptchaLa tidak dapat dijangkau, tolak pengiriman. Nonaktifkan untuk fail open. |
| Use server token | `use.server.token` | `true` | Cetak token server sekali pakai saat render untuk perlindungan anti-replay yang lebih kuat. |

## FAQ

**Apakah plugin ini gratis?**

Ya. Plugin Keycloak ini gratis dan bersumber terbuka. Paket gratis CaptchaLa mencakup 10.000 verifikasi per bulan — paket berbayar hanya berlaku jika Anda butuh volume lebih besar.

**Versi Keycloak mana yang didukung?**

Keycloak 26+ pada distribusi Quarkus, dibangun terhadap 26.5.6 dengan Java 17. Letakkan JAR ke `providers/`, jalankan `kc.sh build`, dan restart.

**Layar mana yang dapat dilindungi?**

Login browser, pendaftaran mandiri, dan reset password. Setiap alur ditambahkan secara terpisah, sehingga Anda dapat melindungi satu, dua, atau ketiganya.

**Apakah App Secret pernah diekspos ke browser?**

Tidak. Rahasia disimpan tersamar dan hanya pernah dikirim di header `X-App-Secret` dari Keycloak ke API CaptchaLa. Tidak pernah muncul di halaman, template, maupun log apa pun. Setiap tantangan diverifikasi dengan token sekali pakai, sehingga token yang sudah diselesaikan tidak dapat diputar ulang.

**Apa yang terjadi jika API CaptchaLa tidak dapat dijangkau?**

Secara default plugin gagal tertutup (pengiriman ditolak). Atur `fail.closed` ke nonaktif pada eksekusi mana pun untuk fail open sebagai gantinya — berguna untuk peluncuran bertahap, tidak disarankan untuk production.

## Sumber

- Repositori plugin: [`github.com/Captcha-La/captchala-keycloak`](https://github.com/Captcha-La/captchala-keycloak)
- Rilis (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- Isu / permintaan fitur: diajukan ke repositori di atas
- Terkait: [Web SDK](/id/web-sdk) · [Referensi API](/id/api-reference)