---
type: how-to
title: Keycloak
summary: "Keycloak의 로그인, 비밀번호 재설정, 회원가입을 Caputchin으로 게이트하세요: extension을 설치하고, 렌더 모드를 고르고, 토큰을 서버 측에서 검증하세요."
---
Keycloak은 서버이지, 스크립트를 임베드하는 페이지가 아닙니다. 그래서 Caputchin은 Keycloak **extension**으로 옵니다: Keycloak에 떨궈 넣는 provider JAR입니다. 이것이 로그인, 비밀번호 재설정, 회원가입 페이지에 Caputchin 위젯을 렌더링하고, 흐름이 진행되기 전에 Keycloak 내부에서 토큰을 검증합니다. 체크박스 위젯도 게임도 모두 동작합니다.
이 extension은 오픈 소스입니다. 전체 레퍼런스(모든 설정 속성, realm 익스포트 JSON, theme 계약, 호환성 매트릭스)는 저장소에 있습니다: [github.com/Caputchin/caputchin-keycloak](https://github.com/Caputchin/caputchin-keycloak).
Keycloak 26.x(Quarkus 배포판)에서 동작합니다. provider JAR을 추가하고 `kc.sh build`를 실행하려면 Keycloak 배포에 대한 접근이 필요합니다; 이것은 호스팅된 마켓플레이스 앱이 아닙니다.
## 1. extension 설치하기
provider JAR을 빌드해 Keycloak에 놓고, 그다음 다시 빌드하세요:
```bash
# 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 --optimized
```
Keycloak이 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-token`입니다. 전체 속성 계약과 Keycloakify 예제는 [저장소의 theme 가이드](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md)에 있습니다.
## 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 대시보드](https://caputchin.com)에서 사이트 키 자체에 한 번만 설정하므로, 여기서 되풀이하지 않습니다.
## 5. Content Security Policy에서 위젯 허용하기
Keycloak의 기본 로그인 CSP는 위젯이 필요로 하는 것보다 엄격합니다. **Realm Settings → Security Defenses → Content Security Policy**에서 로더 스크립트, 검증 호스트, WebAssembly를 허용하세요. 정확한 값은 [저장소의 CSP 가이드](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md)에 있습니다.
서버 측 검증(Keycloak에서 검증 호스트로)은 서버 대 서버 호출이며 브라우저 CSP의 영향을 받지 않습니다. 영향을 받는 것은 브라우저 측 위젯 트래픽뿐입니다.
## 로컬에서 시험하기
저장소에는 로컬 Caputchin 스택에 연결된 한 명령짜리 로컬 Keycloak(`e2e/`)이 들어 있어, 배포 전에 게이트된 세 흐름을 모두 클릭해 볼 수 있습니다. [저장소 README](https://github.com/Caputchin/caputchin-keycloak)를 보세요.