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	—	서버 시크릿. 필수. 마스킹 저장되며 브라우저에 노출되지 않습니다.
렌더 모드	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 레퍼런스