---
title: Keycloak
---

# Keycloak

Keycloak için resmi CaptchaLa eklentisi. Keycloak'ın yerleşik giriş, kayıt ve parola sıfırlama ekranlarına kod yazmadan CAPTCHA doğrulaması ekler, sunucu tarafında doğrular. Keycloak'a bırakacağınız tek bir provider JAR olarak sunulur.

## Kapsadıkları

Aşağıdaki her akış, ayrı bir kimlik doğrulama adımı olarak eklenir — yalnızca korumak istediğiniz ekranları korursunuz.

- Tarayıcı girişi (kullanıcı adı / parola formu)
- Kendi kendine kayıt
- Parola sıfırlama ("parolamı unuttum" ekranı)

Doğrulama, varsayılan olarak kayan bir widget (`float`) ya da tıkla-aç modal (`popup`) şeklinde görüntülenir.

## Kurulum

### 1. JAR dosyasını edinin

Eklenti şu adreste açık kaynak olarak mevcuttur:
[**github.com/Captcha-La/captchala-keycloak**](https://github.com/Captcha-La/captchala-keycloak). İki seçenek:

- **Sürümü indirin** (önerilir) — deponun Releases sayfasından `keycloak-captchala-<version>.jar` dosyasını alın.
- **Kaynaktan derleyin** — depoyu `git clone` ile klonlayın ve `mvn clean package` komutunu çalıştırın; JAR dosyası `target/` klasöründe oluşturulur.

Eklenti, Keycloak ≥ 26 (Quarkus) ve Java 17 hedefler.

### 2. Dağıtın

```bash
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# Keycloak'ı yeniden başlatın
```

Ardından giriş temasını ayarlayın: **Realm settings → Themes → Login theme → `captchala`**.

### 3. Anahtarlarınızı alın

[`dash.captcha.la`](https://dash.captcha.la) üzerinden kaydolun, bir uygulama oluşturun ve şunları kopyalayın:

- **App Key** — genel, sayfaya gömülür
- **App Secret** — yalnızca sunucu tarafı, Keycloak tarafından tek kullanımlık token oluşturmak ve `/v1/validate` çağırmak için kullanılır

### 4. Akışları bağlayın

Yönetici konsolunda, korumak istediğiniz her akışa eşleşen yürütmeyi ekleyin, ardından **App Key** ve **App Secret** anahtarlarınızı yapıştırmak için dişli simgesine tıklayın:

- **Tarayıcı girişi** — *browser* akışını kopyalayın, **Username Password Form** yerine **Captchala Username Password Form** (REQUIRED) koyun, realm browser akışı olarak bağlayın.
- **Kayıt** — *registration* akışını kopyalayın, kayıt formu alt akışına **Captchala Registration** (REQUIRED) ekleyin, realm registration akışı olarak bağlayın.
- **Parola sıfırlama** — *reset credentials* akışını kopyalayın, **Choose User** yerine **Captchala Reset Credential (choose user)** (REQUIRED) koyun, realm reset-credentials akışı olarak bağlayın.

Doğrulamanın görüntülendiğini onaylamak için korunan ekranlardan birini gizli pencerede açın.

## Yapılandırma

Her yürütme, kendi dişli simgesinden bağımsız olarak yapılandırılır. Anahtarlar ayarlandıktan sonra varsayılanlar hemen çalışır.

| Ayar | Anahtar | Varsayılan | Açıklama |
| --- | --- | --- | --- |
| App Key | `app.key` | — | CaptchaLa panosundan alınan public anahtar. Zorunlu. |
| App Secret | `app.secret` | — | Sunucu gizli anahtarı. Zorunlu. Maskelenmiş saklanır, tarayıcıya asla açılmaz. |
| API temel URL'i | `api.base` | `https://apiv1.captcha.la` | CaptchaLa API tabanı. |
| Widget script URL'i | `script.url` | `https://api.captcha.la/sdk/jslib/captchala.js` | Widget JS'nin yüklendiği adres. |
| Widget CSS URL'i | `css.url` | `https://api.captcha.la/sdk/jslib/captchala.css` | Widget CSS'nin yüklendiği adres. |
| Görüntüleme modu | `product` | `float` | `float` (kayan widget) veya `popup` (modal). |
| Eylem etiketi | `action` | akış başına | Doğrulamada gönderilen `action` (`login`, `register`, `reset`). |
| Dil | `language` | realm locale | Widget dili; boş bırakılırsa Keycloak locale'ini takip eder. |
| Kapalı başarısız | `fail.closed` | `true` | CaptchaLa API'sine erişilemediğinde gönderimi reddeder. Açık başarısız için kapatın. |
| Sunucu token kullan | `use.server.token` | `true` | Daha güçlü yeniden oynatma koruması için görüntülemede tek kullanımlık sunucu token'ı oluşturur. |

## SSS

**Eklenti ücretsiz mi?**

Evet. Keycloak eklentisi ücretsiz ve açık kaynaktır. CaptchaLa ücretsiz planı ayda 10.000 doğrulamayı kapsar — ücretli planlar yalnızca daha fazla hacme ihtiyacınız varsa geçerlidir.

**Hangi Keycloak sürümleri destekleniyor?**

Quarkus dağıtımında Keycloak 26+, Java 17 ile 26.5.6 sürümüne göre derlendi. JAR'ı `providers/` klasörüne bırakın, `kc.sh build` komutunu çalıştırın ve yeniden başlatın.

**Hangi ekranları koruyabilir?**

Tarayıcı girişi, kendi kendine kayıt ve parola sıfırlama. Her biri akışına bağımsız olarak eklenir, dolayısıyla birini, ikisini veya üçünü de koruyabilirsiniz.

**App Secret tarayıcıya hiç açılıyor mu?**

Hayır. Gizli anahtar maskelenmiş olarak saklanır ve yalnızca Keycloak'tan CaptchaLa API'sine `X-App-Secret` başlığında gönderilir. Herhangi bir sayfada, şablonda veya günlükte hiç görünmez. Her doğrulama tek kullanımlık bir token ile doğrulanır, dolayısıyla çözülen bir token yeniden kullanılamaz.

**CaptchaLa API'sine erişilemezse ne olur?**

Varsayılan olarak eklenti kapalı başarısız olur (gönderim reddedilir). Açık başarısız yapmak için herhangi bir yürütmede `fail.closed` seçeneğini kapatın — aşamalı dağıtım için kullanışlıdır, üretim için önerilmez.

## Kaynak

- Eklenti deposu: [`github.com/Captcha-La/captchala-keycloak`](https://github.com/Captcha-La/captchala-keycloak)
- Sürümler (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- Sorunlar / özellik talepleri: yukarıdaki depoya kaydedilir
- İlgili: [Web SDK](/tr/web-sdk) · [API Referansı](/tr/api-reference)