Keycloak

Keycloak은 서버이지, 스크립트를 임베드하는 페이지가 아닙니다. 그래서 Caputchin은 Keycloak extension으로 제공됩니다: Keycloak에 추가하는 provider JAR입니다. 이것이 로그인, 비밀번호 재설정, 회원가입 페이지에 Caputchin 위젯을 렌더링하고, 흐름이 진행되기 전에 Keycloak 내부에서 토큰을 검증합니다. 체크박스 위젯도 게임도 모두 동작합니다.

이 extension은 오픈 소스입니다. 전체 레퍼런스(모든 설정 속성, realm 익스포트 JSON, theme 계약, 호환성 매트릭스)는 저장소에 있습니다: github.com/Caputchin/caputchin-keycloak. 새 계정에서 첫 서버 검증 세션까지 15분 정도 걸린다고 보면 됩니다.

1. 사이트 키 만들기

caputchin.com/login에서 로그인하고(첫 로그인 때 계정이 만들어집니다), 개인 팀을 연 다음 사이트 키 만들기를 클릭하고, Keycloak realm 이름을 따서 이름을 붙인 뒤 만들기를 클릭하세요. 두 값을 모두 복사하세요:

• 공개 키(cpt_pub_...)
• 시크릿(cpt_sec_...). 한 번만 표시됩니다.

계정과 첫 사이트 키 만들기에서 같은 화면을 더 자세히 안내합니다.

2. extension 설치하기

최신 릴리스에서 caputchin-keycloak.jar를 내려받아 Keycloak의 providers/ 디렉터리에 복사하고, 다시 빌드하세요:

cp caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimized

Keycloak이 provider를 발견하려면 kc.sh build가 필요합니다. 컨테이너 이미지에서는 이미지 안에서 JAR을 복사하고 빌드를 실행하세요:

FROM quay.io/keycloak/keycloak:26.4
COPY caputchin-keycloak.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

대신 소스에서 JAR을 빌드하려면 저장소의 설치 가이드를 보세요.

3. Keycloak에 시크릿 전달하기

시크릿은 realm 구성에 넣지 마세요: Keycloak 서버에 환경 변수(예: CAPUTCHIN_SECRET)로 설정하고 Keycloak을 재시작하세요. 5단계에서는 변수 이름만 입력합니다. 시크릿을 직접 입력하거나 ${vault.*} 참조를 써도 됩니다. 저장소의 설정 가이드를 보세요.

4. 위젯이 렌더링되는 방식 고르기

두 가지 방식이 있고, realm마다 고릅니다.

턴키: 동봉된 theme

JAR에는 caputchin 로그인 theme가 함께 들어 있습니다. Admin Console에서 realm을 열고 Realm settings → Themes로 가서 Login theme를 caputchin으로 설정한 뒤 Save를 클릭하세요. 템플릿 편집 없이 로그인, 재설정, 회원가입 페이지에 위젯이 렌더링됩니다. 표준 Keycloak 로그인을 쓴다면 이것이 가장 빠른 길입니다.

헤드리스: 자체 theme가 위젯을 렌더링

자체 로그인 theme(예: Keycloakify React theme)를 쓴다면, theme는 그대로 두고 extension을 헤드리스로 돌리세요. extension은 위젯 구성을 페이지 컨텍스트로 노출하고 토큰을 검증하며, theme가 <caputchin-widget>(또는 <caputchin-game>) 요소를 렌더링합니다. 토큰 필드는 caputchin-token입니다. 전체 속성 계약과 Keycloakify 예제는 저장소의 theme 가이드에 있습니다.

5. 로그인 흐름에 묶기

Keycloak은 단계의 authenticator를 그 자리에서 바꾸지 않으므로, 흐름의 사본에 Caputchin 단계를 추가하고 원래 단계를 제거합니다.

1. Authentication으로 가세요. browser 흐름에서 메뉴(⋮)를 열고 Duplicate를 클릭한 뒤, 사본에 이름을 붙이고(예: browser caputchin) Duplicate를 클릭하세요.

2. 사본에서 forms 하위 흐름을 찾으세요. 그 +(Add) 버튼을 클릭하고 Add execution을 고른 뒤 Caputchin Username Password Form을 선택하고 Add를 클릭하세요.

3. 새 단계를 forms 하위 흐름의 맨 위, Conditional 2FA 하위 흐름 위로 끌어 놓아, 예전 단계가 실행되던 자리에서 실행되게 하세요. 요구 사항은 Required입니다.

4. forms 하위 흐름에서 원래의 Username Password Form 단계를 삭제하세요.

5. Caputchin 단계의 톱니바퀴(Settings)를 클릭하고 다음을 입력하세요:

   • Alias: 아무 이름, 예: caputchin-login.
   • Site key: 공개 키(cpt_pub_...). 브라우저로 보내지는 유일한 값입니다.
   • Secret key env var: 3단계의 변수 이름, 예: CAPUTCHIN_SECRET.

   그런 다음 Save를 클릭하세요. 나머지 칸에는 바로 쓸 수 있는 기본값이 있습니다: Widget mode는 checkbox(또는 invisible, game), Locale은 kc(realm의 locale을 따름), Fail closed는 켜짐이라 검증 장애 시 로그인을 통과시키는 대신 막습니다.

6. 흐름의 Action 메뉴를 열고 Bind flow를 클릭한 뒤, Browser flow를 그대로 두고 Save를 클릭하세요.

챌린지는 별도 단계가 아니라 자격 증명과 같은 페이지에 렌더링됩니다. 기본 설정에서는 사용자가 Sign In을 클릭할 때 확인이 실행됩니다.

비밀번호 재설정과 회원가입

같은 방식으로 나머지 두 폼도 보호합니다:

Caputchin 단계마다 자체 설정(톱니바퀴)이 있으니, 각각에 사이트 키와 시크릿 변수를 입력하세요. direct grant 흐름에는 챌린지를 추가하지 마세요: 거기엔 브라우저가 없어서 API 토큰 요청을 깨뜨립니다. 저장소의 흐름에 묶기에서 같은 설정을 realm 익스포트 JSON으로 보여 줍니다.

더 풍부한 모습(어떤 게임, 스킨, 브랜드)은 Caputchin 대시보드에서 사이트 키 자체에 한 번만 설정하므로, Keycloak에서 되풀이하지 않습니다.

6. Content Security Policy 확인하기

Keycloak의 기본 로그인 Content Security Policy(Realm settings → Security defenses → Headers 아래)는 frame-src 'self'; frame-ancestors 'self'; object-src 'none';입니다. 이것은 스크립트나 연결이 아니라 프레임을 제한하며, 게임은 srcdoc 프레임에서 실행되므로 체크박스, invisible 위젯, 게임 모두 이 정책 그대로 동작합니다.

자체적으로 더 엄격한 정책을 설정한다면 저장소의 CSP 가이드에 있는 것에서 시작하세요. script-src 지시어는 Keycloak 자체의 인라인 스크립트에도 적용되므로, 무엇이든 바꾼 뒤에는 로그인 페이지와 Account Console을 테스트하세요.

서버 측 검증(Keycloak에서 검증 호스트로)은 서버 대 서버 호출이며 브라우저 정책의 영향을 받지 않습니다.

7. 첫 서버 검증 세션 확인하기

1. 시크릿 창에서 애플리케이션의 로그인(또는 realm의 로그인 페이지)을 여세요.
2. 테스트 사용자로 로그인하세요. Sign In을 클릭하면 위젯이 실행되고, Keycloak이 로그인시켜 줍니다.
3. Caputchin 대시보드에서 팀을 열고 사이트 키를 클릭하세요. 통계를 새로 고치세요.

이제 서버에서 검증됨이 1 이상이면, Keycloak이 Caputchin으로 토큰을 확인한 것입니다. 이것이 첫 검증 세션입니다. 로그인 페이지에 "Verification failed. Please complete the check and try again."이 표시되고 서버에서 검증됨이 0에 머문다면, 토큰이 Keycloak에 닿지 않은 것입니다: 브라우저 콘솔에서 Content Security Policy 오류를 확인하세요(6단계). 브라우저에서 통과는 올랐는데 로그인이 여전히 실패한다면, 3단계의 시크릿 변수가 서버에 설정되어 있는지 확인하세요. 통계와 세션에서 각 숫자를 설명합니다.

로컬에서 시험하기

저장소에는 로컬 Caputchin 스택에 연결된 한 명령짜리 로컬 Keycloak(e2e/)이 들어 있어, 배포 전에 게이트된 세 흐름을 모두 클릭해 볼 수 있습니다. 저장소 README를 보세요.

함께 보기

• 사이트 키 개요
• WordPress