---
title: Keycloak
---

# Keycloak

CaptchaLa 공식 Keycloak 플러그인. 코드를 작성하지 않고 Keycloak의 기본 로그인, 회원가입, 비밀번호 재설정 화면에 CAPTCHA 검증을 추가합니다. 서버 측에서 검증하며, Keycloak에 드롭인하는 단일 provider JAR로 제공됩니다.

## 보호 대상

아래 각 플로우는 독립된 인증 단계로 추가됩니다 — 원하는 화면만 선택해 보호할 수 있습니다.

- 브라우저 로그인 (아이디 / 비밀번호 폼)
- 자체 회원가입
- 비밀번호 재설정 ("비밀번호 찾기" 화면)

챌린지는 기본적으로 플로팅 위젯(`float`)으로 렌더링되거나, 클릭 시 열리는 모달(`popup`)로도 설정할 수 있습니다.

## 설치

### 1. JAR 받기

플러그인은 오픈소스로 공개되어 있습니다:
[**github.com/Captcha-La/captchala-keycloak**](https://github.com/Captcha-La/captchala-keycloak). 두 가지 방법이 있습니다.

- **릴리스 다운로드** (권장) — 저장소의 Releases 페이지에서 `keycloak-captchala-<버전>.jar`를 받습니다.
- **소스에서 빌드** — `git clone` 후 `mvn clean package`를 실행합니다. JAR은 `target/` 아래에 생성됩니다.

이 플러그인은 Keycloak ≥ 26 (Quarkus) 및 Java 17을 대상으로 합니다.

### 2. 배포

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

이후 로그인 테마를 설정합니다: **Realm settings → Themes → Login theme → `captchala`**.

### 3. 키 발급

[`dash.captcha.la`](https://dash.captcha.la)에서 가입 후 애플리케이션을 만들고 아래를 복사합니다.

- **App Key** — 공개 키, 페이지에 임베드됩니다
- **App Secret** — 서버 전용. Keycloak이 일회용 토큰을 발급하고 `/v1/validate`를 호출할 때 사용합니다

### 4. 플로우 연결

관리자 콘솔에서 보호할 각 플로우에 맞는 execution을 추가한 뒤, 기어 아이콘을 클릭해 **App Key**와 **App Secret**을 붙여넣습니다.

- **브라우저 로그인** — *browser* 플로우를 복제하고, **Username Password Form**을 **Captchala Username Password Form** (REQUIRED)으로 교체한 뒤 realm 브라우저 플로우로 바인딩합니다.
- **회원가입** — *registration* 플로우를 복제하고, registration-form 하위 플로우에 **Captchala Registration** (REQUIRED)을 추가한 뒤 realm 회원가입 플로우로 바인딩합니다.
- **비밀번호 재설정** — *reset credentials* 플로우를 복제하고, **Choose User**를 **Captchala Reset Credential (choose user)** (REQUIRED)으로 교체한 뒤 realm reset-credentials 플로우로 바인딩합니다.

보호된 화면 중 하나를 시크릿 창에서 열어 챌린지가 정상적으로 렌더링되는지 확인합니다.

## 설정 항목

각 execution은 기어 아이콘에서 독립적으로 설정합니다. 키만 입력하면 기본값으로 바로 사용할 수 있습니다.

| 설정 | Key | 기본값 | 설명 |
| --- | --- | --- | --- |
| App Key | `app.key` | — | CaptchaLa 대시보드의 공개 키. 필수. |
| App Secret | `app.secret` | — | 서버 시크릿. 필수. 마스킹 저장되며 브라우저에 노출되지 않습니다. |
| API base URL | `api.base` | `https://apiv1.captcha.la` | CaptchaLa API 베이스 주소. |
| 위젯 스크립트 URL | `script.url` | `https://api.captcha.la/sdk/jslib/captchala.js` | 위젯 JS를 로드하는 위치. |
| 위젯 CSS URL | `css.url` | `https://api.captcha.la/sdk/jslib/captchala.css` | 위젯 CSS를 로드하는 위치. |
| 렌더 모드 | `product` | `float` | `float`(플로팅 위젯) 또는 `popup`(모달). |
| Action 라벨 | `action` | 플로우별 | 검증 시 전송하는 `action`(`login`, `register`, `reset`). |
| 언어 | `language` | realm 로케일 | 위젯 언어. 비워두면 Keycloak 로케일을 따릅니다. |
| 장애 시 차단 | `fail.closed` | `true` | CaptchaLa API에 도달할 수 없을 때 제출을 거부합니다. 비활성화하면 페일 오픈으로 전환됩니다. |
| 서버 토큰 사용 | `use.server.token` | `true` | 렌더 시 일회용 서버 토큰을 발급해 재전송 공격에 더 강하게 대응합니다. |

## 자주 묻는 질문

**플러그인은 무료인가요?**

네. Keycloak 플러그인은 무료 오픈소스입니다. CaptchaLa 무료 플랜은 월 10,000회 검증을 포함합니다 — 더 많은 사용량이 필요한 경우에만 유료 플랜이 적용됩니다.

**어떤 Keycloak 버전이 지원되나요?**

Quarkus 배포판 기준 Keycloak 26+이며, Java 17로 26.5.6에 맞춰 빌드되었습니다. JAR을 `providers/`에 드롭하고 `kc.sh build`를 실행한 뒤 재시작하세요.

**어떤 화면을 보호할 수 있나요?**

브라우저 로그인, 자체 회원가입, 비밀번호 재설정. 각 항목은 플로우에 독립적으로 추가되므로 하나, 둘, 또는 세 가지 모두 보호할 수 있습니다.

**App Secret이 브라우저에 노출되나요?**

아닙니다. 시크릿은 마스킹 저장되며, Keycloak에서 CaptchaLa API로 전송하는 `X-App-Secret` 헤더에서만 사용됩니다. 페이지, 템플릿, 로그 어디에도 나타나지 않습니다. 각 챌린지는 일회용 토큰으로 검증되므로 해결된 토큰은 재전송할 수 없습니다.

**CaptchaLa API에 도달할 수 없으면 어떻게 되나요?**

기본적으로 플러그인은 장애 시 차단(fail-closed) 방식으로 동작해 제출을 거부합니다. 단계적 출시를 위해 특정 execution에서 페일 오픈으로 설정할 수 있지만, 운영 환경에는 권장하지 않습니다.

## 소스

- 플러그인 저장소: [`github.com/Captcha-La/captchala-keycloak`](https://github.com/Captcha-La/captchala-keycloak)
- 릴리스 (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- 이슈 / 기능 요청: 위 저장소에 등록
- 관련 문서: [Web SDK](/ko/web-sdk) · [API 레퍼런스](/ko/api-reference)