Keycloak 플로우에 CAPTCHA 추가
서버 측 검증 챌린지로 Keycloak 브라우저 로그인, 자체 회원가입, 비밀번호 재설정 화면을 보호합니다. provider JAR 하나, 코드 불필요.
왜 Keycloak에 CaptchaLa인가
봇이 가장 먼저 노리는 화면에서 서버 측 검증을 제공합니다.
프라이버시 우선
제3자 추적 픽셀과 광고 시그널이 없습니다. 사용자는 프로파일링되지 않습니다. GDPR, CCPA, PIPL을 기본 준수합니다.
서버 측 재전송 방지
Keycloak이 렌더 시 일회용 토큰을 발급하고 App Secret으로 서버 측 검증합니다. 해결된 토큰은 재사용하거나 폼 간에 공유할 수 없습니다.
드롭인, 코드 불필요
providers/에 provider JAR 하나를 넣고 kc.sh build를 실행한 뒤, 플로우에 execution을 추가하고 키 두 개만 붙여넣으면 됩니다. 시크릿은 브라우저에 도달하지 않습니다.
보호 위치
인증 설정에서 각 플로우를 독립적으로 추가합니다.
3단계로 설치
provider를 배포한 뒤 플로우를 연결합니다.
- 1
JAR 배포
keycloak-captchala.jar를 /opt/keycloak/providers/에 복사하고, kc.sh build를 실행한 뒤 재시작합니다. 로그인 테마를 'captchala'로 설정하세요.
- 2
App Key와 App Secret 붙여넣기
captcha.la에서 가입 후 App Key와 App Secret을 복사해 Captchala execution 설정(기어 아이콘)에 붙여넣습니다.
- 3
보호할 플로우 선택
browser, registration, reset-credentials 플로우에 Captchala 단계를 추가합니다 — 로그인, 회원가입, 비밀번호 재설정, 완료.
자주 묻는 질문
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을 페일 오픈으로 전환할 수 있습니다.