Keycloak
Keycloak은 서버이지, 스크립트를 임베드하는 페이지가 아닙니다. 그래서 Caputchin은 Keycloak extension으로 옵니다: Keycloak에 떨궈 넣는 provider JAR입니다. 이것이 로그인, 비밀번호 재설정, 회원가입 페이지에 Caputchin 위젯을 렌더링하고, 흐름이 진행되기 전에 Keycloak 내부에서 토큰을 검증합니다. 체크박스 위젯도 게임도 모두 동작합니다.
이 extension은 오픈 소스입니다. 전체 레퍼런스(모든 설정 속성, realm 익스포트 JSON, theme 계약, 호환성 매트릭스)는 저장소에 있습니다: github.com/Caputchin/caputchin-keycloak.
1. extension 설치하기
provider JAR을 빌드해 Keycloak에 놓고, 그다음 다시 빌드하세요:
# build (no JDK on the host? run it in Docker)
docker run --rm -v "$PWD":/work -w /work maven:3.9-eclipse-temurin-21 mvn -DskipTests package
cp target/caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimizedKeycloak이 provider를 발견하려면 kc.sh build가 필요합니다.
2. 위젯이 렌더링되는 방식 고르기
두 가지 방식이 있고, realm마다 고릅니다.
턴키: 동봉된 theme(별도 theme 불필요)
JAR은 caputchin 로그인 theme를 함께 담고 있습니다. **Realm Settings → Themes → Login theme: caputchin**에서 설정하면, 템플릿 편집 없이 로그인, 재설정, 회원가입 페이지에 위젯이 렌더링됩니다. 표준 Keycloak 로그인을 쓴다면 이것이 가장 빠른 길입니다.
헤드리스: 당신의 theme가 위젯을 렌더링
자체 로그인 theme(예: Keycloakify React theme)를 내보낸다면, 당신의 theme를 유지하고 extension을 헤드리스로 돌리세요. 이것은 위젯 구성을 페이지 컨텍스트로 노출하고 토큰을 검증합니다; 당신의 theme가 <caputchin-widget>(또는 <caputchin-game>) 요소를 렌더링하고 당신의 디자인 토큰으로 스타일을 입힙니다. 토큰 필드는 caputchin-token입니다. 전체 속성 계약과 Keycloakify 예제는 저장소의 theme 가이드에 있습니다.
3. 당신의 흐름에 묶기
Authentication → Flows에서, 보호하려는 흐름을 복제하고 execution을 바꾸세요:
| 흐름 | execution을 이것으로 설정 |
|---|---|
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | 회원가입 폼에 Caputchin 추가 |
로그인과 재설정 챌린지는 별도 단계가 아니라 자격 증명과 같은 페이지에 렌더링됩니다. 각 execution의 설정(톱니바퀴)을 열어 당신의 키를 설정하세요. direct grant 흐름에는 챌린지를 추가하지 마세요: 거기엔 브라우저가 없어서, API 토큰 요청을 깨뜨릴 것입니다.
4. 키 구성하기
execution 설정에서 다음을 설정하세요:
- 사이트 키: 당신의 공개 키(
cpt_pub_...). 브라우저로 보내지는 유일한 값입니다. - 시크릿 키: 당신의 시크릿(
cpt_sec_...). 리터럴로 저장하거나, 환경 변수를 가리키거나(realm 익스포트에 결코 들어가지 않도록),${vault.*}참조를 쓸 수 있습니다. - 위젯 모드:
checkbox,invisible, 또는game. 더해 크기, locale(기본값은 realm의 locale을 따름), 스킨. - Fail closed: 기본으로 켜져 있어, 검증 장애 시 봇을 통과시키는 대신 막습니다.
더 풍부한 모습(어떤 게임, 스킨, 브랜드)은 Caputchin 대시보드에서 사이트 키 자체에 한 번만 설정하므로, 여기서 되풀이하지 않습니다.
5. Content Security Policy에서 위젯 허용하기
Keycloak의 기본 로그인 CSP는 위젯이 필요로 하는 것보다 엄격합니다. Realm Settings → Security Defenses → Content Security Policy에서 로더 스크립트, 검증 호스트, WebAssembly를 허용하세요. 정확한 값은 저장소의 CSP 가이드에 있습니다.
로컬에서 시험하기
저장소에는 로컬 Caputchin 스택에 연결된 한 명령짜리 로컬 Keycloak(e2e/)이 들어 있어, 배포 전에 게이트된 세 흐름을 모두 클릭해 볼 수 있습니다. 저장소 README를 보세요.