Keycloak
CaptchaLa 공식 Keycloak 플러그인. 코드를 작성하지 않고 Keycloak의 기본 로그인, 회원가입, 비밀번호 재설정 화면에 CAPTCHA 검증을 추가합니다. 서버 측에서 검증하며, Keycloak에 드롭인하는 단일 provider JAR로 제공됩니다.
보호 대상
아래 각 플로우는 독립된 인증 단계로 추가됩니다 — 원하는 화면만 선택해 보호할 수 있습니다.
- 브라우저 로그인 (아이디 / 비밀번호 폼)
- 자체 회원가입
- 비밀번호 재설정 ("비밀번호 찾기" 화면)
챌린지는 기본적으로 플로팅 위젯(float)으로 렌더링되거나, 클릭 시 열리는 모달(popup)로도 설정할 수 있습니다.
설치
1. JAR 받기
플러그인은 오픈소스로 공개되어 있습니다: github.com/Captcha-La/captchala-keycloak. 두 가지 방법이 있습니다.
- 릴리스 다운로드 (권장) — 저장소의 Releases 페이지에서
keycloak-captchala-<버전>.jar를 받습니다. - 소스에서 빌드 —
git clone후mvn clean package를 실행합니다. JAR은target/아래에 생성됩니다.
이 플러그인은 Keycloak ≥ 26 (Quarkus) 및 Java 17을 대상으로 합니다.
2. 배포
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에서 가입 후 애플리케이션을 만들고 아래를 복사합니다.
- 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 - 릴리스 (JAR):
github.com/Captcha-La/captchala-keycloak/releases - 이슈 / 기능 요청: 위 저장소에 등록
- 관련 문서: Web SDK · API 레퍼런스