본문으로 건너뛰기

주요 기능

Keycloak 26.5.2 기반의 엔터프라이즈 인증 확장 패키지. 복잡한 인증 요구사항을 플러그인 방식으로 해결합니다.

왜 이 패키지인가​

#차별점설명
1Keycloak 순정 유지서버 코드를 수정하지 않고 SPI 플러그인만으로 구현 → 업그레이드 부담 없음
2단일 JAR 배포fat JAR 하나를 providers/에 복사하면 끝. 인프라 추가 설치 불필요
3이용약관 동의 구조화필수·선택 동의 항목을 사용자 속성으로 저장, 버전 관리 및 변경 사전 고지 지원
4휴면 계정 자동 관리개인정보 보호법 기반 미접속 계정 자동 전환·삭제 스케줄러 내장
5국내 소셜 로그인 지원카카오·네이버 OAuth2 + 이니시스 간편인증 확장 아키텍처 제공
6인증 전략 플러그인화OTP 전달 수단, 조건부 Skip, 휴면 체크 등 각 단계를 Flow에서 독립 조합 가능
7이벤트 연동 멀티 채널RabbitMQ / Kafka / Redis 중 환경변수 하나로 선택 — 코드 변경 없이 전환
8개발자 친화적 테스트 모드OTP_DEV_MODE=true 하나로 실제 SMS·이메일 없이 전체 인증 플로우 즉시 테스트
9기존 사용자 DB 연동REST API 연결만으로 외부 사용자 저장소 연동 — 데이터 마이그레이션·재가입 불필요

1. SMS / 이메일 OTP 2단계 인증​

로그인 시 등록된 휴대폰 또는 이메일로 6자리 일회용 코드를 발송하여 계정을 보호합니다.

  • 사용자별 인증 수단 선택 (SMS / EMAIL / SKIP)
  • 전략 기반 전달 방식 — 설정값, 사용자 속성, 사용자 직접 선택 중 선택 가능
  • 인증 코드 Rate limit (30분/5회) 및 TTL 설정 지원
  • 개발 편의를 위한 OTP_DEV_MODE 지원 (000000 항상 통과)

2. 소셜 로그인 (카카오 · 네이버 · 이니시스)​

별도의 아이디·비밀번호 없이 외부 계정으로 즉시 로그인.

제공사방식계정 매핑 기준
카카오OAuth2 / OpenID Connect이메일
네이버OAuth2이메일
KG이니시스간편인증 (목업 포함)CI → 휴대폰 번호
  • 기존 계정과 자동 연동 — 재가입 불필요
  • 이니시스 확장 아키텍처 제공으로 추가 간편인증 연동 용이

3. 이용약관 동의 관리​

회원가입 시 필수/선택 동의 항목을 구조화하여 수집하고 사용자 속성으로 저장.

  • 필수: 서비스 이용약관, 개인정보 수집 동의, 만 14세 이상 확인
  • 선택: 선택 개인정보 수집, 마케팅 수신 동의 (이메일 · SMS · 푸시)
  • 동의 이력이 사용자 속성에 저장되어 언제든 조회 가능
  • 이용약관 갱신 및 재동의 지원
  • 이용약관 버전을 Realm 속성으로 관리, 변경 유형에 따라 사전 고지 자동 발송 (일반: 이메일 7일 전 / 불리한 변경: 이메일+SMS 30일 전)

4. 아이디 찾기 · 비밀번호 재설정​

아이디·비밀번호를 잊어도 OTP 인증만으로 안전하게 복구.

  • 아이디 찾기: 이메일 또는 휴대폰으로 본인 확인 후 아이디 반환
  • 비밀번호 재설정: 아이디 입력 → OTP 인증(이메일/SMS) → 새 비밀번호 설정
  • 최대 인증 실패 횟수 및 잠금 시간 설정 지원

5. 장기 미접속 계정 자동 보호 (휴면 관리)​

개인정보 보호법 대응을 위한 휴면 계정 자동화 처리.

ACTIVE → (365일 미접속) → 경고 이메일(D-30) → DORMANT
       → (90일 경과)   → 삭제 경고 이메일(D-30) → PENDING_DELETE → 삭제(비활성화)
  • 스케줄러 주기, 휴면 기준일, 삭제 기준일 모두 Admin Console에서 설정
  • 휴면 전환 전 사전 안내 이메일 자동 발송
  • 휴면 계정 로그인 시 OTP 인증(6자리)으로 즉시 재활성화
  • 로그인 성공 시 lastLoginDate 자동 갱신

6. 사용자 이벤트 외부 발행 (User Event Publisher)​

사용자 생성·수정·삭제 이벤트를 실시간으로 외부 시스템에 전달.

채널발행 방식기본 설정
RabbitMQtopic exchangeuser.account.created / .updated / .deleted
KafkaProducertopic: user-events
RedisPub/Subchannel: user:events
Log파일 로그채널 미설정 시 fallback
  • 환경변수 USER_EVENT_CHANNEL 하나로 채널 전환
  • 발행 실패 시 주 흐름 차단 없이 자동 Log fallback
  • 이벤트 페이로드에 전체 사용자 상태 포함 (source 필드로 발생 원인 구분)

7. 프로파일 관리 페이지​

로그인된 사용자가 별도 페이지에서 개인정보를 직접 관리.

  • 이름·이메일·휴대폰 번호 조회 및 수정
  • 수정 전 비밀번호 재확인으로 무단 변경 방지
  • 비밀번호 변경

8. 회원가입 인증 (이메일 · SMS 코드 확인)​

가입 시 이메일과 휴대폰 번호를 코드 인증으로 검증.

  • REST API 기반 (/realms/{realm}/registration-verify/)
  • 휴대폰 번호 중복 방지 Validator (phone-uniqueness) 내장
  • Rate limit 및 코드 TTL 설정 가능

9. 커스텀 로그인 테마 (keycloak.ext)​

Tailwind CSS 기반의 커스텀 UI 테마 내장.

  • 로그인·회원가입·OTP·비밀번호 재설정·약관 동의 등 전체 화면 커버
  • SPI JAR에 번들되어 별도 파일 배포 불필요
  • 한국어(ko) / 영어(en) 다국어 지원
  • 다크모드 지원(keycloak.ext-dark 테마선택)

10. 외부 사용자 저장소 연동 (User Storage Provider)​

기존 외부 시스템의 사용자 DB를 Keycloak과 연동하여 재가입 없이 그대로 사용.

  • REST API 기반 연동 — Base URL + BasicAuth 설정만으로 외부 사용자 조회·인증
  • 자격증명 위임 — 비밀번호 검증을 외부 시스템에 위임, Keycloak DB에 저장 불필요
  • 속성 라우팅 — 시스템 속성(username, email 등)은 Keycloak, 커스텀 속성은 외부 API로 자동 분리 저장
  • 읽기·쓰기·검색 모두 지원 (UserLookupProvider, UserQueryProvider, UserRegistrationProvider)
로그인 시:
  1. Keycloak → 외부 REST API로 사용자 조회
  2. 외부 API → 비밀번호 검증
  3. 인증 성공 시 Keycloak 세션 발급

시스템 요구사항​

항목요구사항
Keycloak26.5.2
Java17
배포 방식fat JAR (providers 디렉토리 배포)