Keycloak Extensions - Korean Social Identity Providers

말 그대로 Keycloak의 확장 기능!!! Keycloak Extensions for Korean Social Logins!

프로젝트 개요 (Overview)

이 프로젝트는 한국의 주요 소셜 로그인 서비스들을 Keycloak과 통합할 수 있는 Identity Provider 확장을 제공합니다.

This project provides Keycloak identity provider extensions for popular Korean social login services and international OAuth2 providers.

지원하는 소셜 로그인 (Supported Providers)

한국 소셜 로그인 서비스

• Kakao (카카오) - 한국에서 가장 인기 있는 메시징 플랫폼
• LINE (라인) - 한국과 일본에서 널리 사용되는 메시징 앱
• Naver (네이버) - 한국의 대표적인 검색 엔진 및 웹 포털

글로벌 소셜 로그인 서비스

• Google - 구글 계정으로 로그인 (OpenID Connect 지원)
• GitHub - 깃허브 계정으로 로그인

Event Listener 확장

Keycloak 이벤트를 다양한 메시징 시스템으로 실시간 스트리밍:

메시징 시스템 지원

• Kafka - Apache Kafka로 이벤트 스트리밍
• RabbitMQ - RabbitMQ 메시지 큐로 이벤트 전송
• NATS - NATS 메시징 시스템 통합
• Redis - Redis Pub/Sub로 이벤트 발행
• MQTT - MQTT 브로커로 IoT 통합 ✨ NEW
• AWS - AWS SNS/SQS로 이벤트 전송
• Azure - Azure Service Bus/Event Grid 통합

Event Listener 주요 기능

• Resilience Patterns: Circuit Breaker, Retry, Dead Letter Queue, Batch Processing
• Metrics & Monitoring: Prometheus 메트릭, 실시간 모니터링
• Security: TLS/SSL, 인증, 암호화 지원
• High Performance: 비동기 처리, 배치 처리, 연결 풀링
• Production-Ready: 완전한 에러 처리, 로깅, 테스트 커버리지

🏢 Realm 관리 확장

Keycloak Realm의 고급 관리 기능 제공:

Realm Hierarchy Manager ✨ NEW

• 계층 구조: Realm 간 부모-자식 관계 설정
• 설정 상속: Identity Provider, Role 자동 상속
• 자동 동기화: 부모 Realm 변경사항 자동 전파
• REST API: 계층 구조 관리용 완전한 REST API
• 이벤트 기반: Realm 변경 자동 감지 및 처리

사용 사례:

• 엔터프라이즈 SaaS (대기업 → 자회사 → 지사)
• 멀티테넌트 플랫폼 (플랫폼 → 테넌트 → 환경)
• 대규모 조직 (본사 → 부서 → 팀)

자세한 내용은 Realm Hierarchy 문서를 참조하세요.

🎨 기업용 로그인 테마

깔끔하고 모던한 기업 환경용 Keycloak 로그인 테마 제공:

Corporate Clean Theme

• 미니멀 디자인: 깔끔하고 전문적인 UI
• 반응형 지원: 데스크톱, 태블릿, 모바일 완벽 대응
• 다국어 지원: 영어, 한국어, 일본어
• 소셜 로그인 스타일링: Kakao, Naver, Google, GitHub, LINE 등
• 접근성: WCAG 2.1 AA 준수
• 커스터마이징: 색상, 로고, 배경 쉽게 변경 가능

자세한 내용은 테마 문서를 참조하세요.

주요 기능 (Features)

• 각 플랫폼과의 완전한 OAuth2 통합
• 자동 사용자 속성 매핑
• 프로필 이미지, 이메일 등 사용자 속성 지원
• 커스텀 속성 매퍼 지원
• 포괄적인 에러 처리로 프로덕션 환경 대응
• 모든 컴포넌트에 대한 단위 테스트
• GitHub Actions CI/CD 파이프라인 지원

요구사항 (Requirements)

• Keycloak 26.3.1 이상
• Java 21 이상
• Gradle 8.8 (wrapper 포함)

빠른 시작 (Quick Start)

프로젝트 빌드

1. 저장소 클론:

   git clone https://github.com/yourusername/sb-keycloak-exts.git
   cd sb-keycloak-exts

2. 모든 provider 빌드:

   ./gradlew shadowJar

3. JAR 파일 생성 위치:

   Identity Providers:

   • idps/idp-kakao/build/libs/idp-kakao-*-all.jar
   • idps/idp-line/build/libs/idp-line-*-all.jar
   • idps/idp-naver/build/libs/idp-naver-*-all.jar
   • idps/idp-google/build/libs/idp-google-*-all.jar
   • idps/idp-github/build/libs/idp-github-*-all.jar

   Event Listeners:

   • events/event-listener-kafka/build/libs/keycloak-kafka-event-listener-*-all.jar
   • events/event-listener-rabbitmq/build/libs/keycloak-rabbitmq-event-listener-*-all.jar
   • events/event-listener-nats/build/libs/keycloak-nats-event-listener-*-all.jar
   • events/event-listener-redis/build/libs/keycloak-redis-event-listener-*-all.jar
   • events/event-listener-mqtt/build/libs/keycloak-mqtt-event-listener-*-all.jar ✨
   • events/event-listener-aws/build/libs/keycloak-aws-event-listener-*-all.jar
   • events/event-listener-azure/build/libs/keycloak-azure-event-listener-*-all.jar

   Realm Management:

   • realms/realm-hierarchy/build/libs/realm-hierarchy-*-all.jar ✨

   Corporate Themes:

   • themes/build/libs/keycloak-theme-corporate-clean.jar 🎨
   • themes/build/libs/keycloak-theme-corporate-base.jar

설치

1. 원하는 확장 JAR를 Keycloak에 복사:

   # Identity Providers
   cp idps/idp-*/build/libs/*-all.jar $KEYCLOAK_HOME/providers/
   
   # Event Listeners (선택사항)
   cp events/event-listener-*/build/libs/*-all.jar $KEYCLOAK_HOME/providers/
   
   # Corporate Themes (선택사항) 🎨
   cp themes/build/libs/*.jar $KEYCLOAK_HOME/providers/

2. Keycloak 빌드 및 재시작:

   $KEYCLOAK_HOME/bin/kc.sh build
   $KEYCLOAK_HOME/bin/kc.sh start

3. (테마 사용 시) Keycloak 관리 콘솔에서 테마 설정:

   • Realm Settings → Themes → Login Theme: corporate-clean 선택

설정 가이드 (Configuration Guide)

1. 소셜 애플리케이션 설정

각 소셜 플랫폼에서 애플리케이션을 생성해야 합니다:

한국 소셜 플랫폼

• Kakao: Kakao Developers Console
• LINE: LINE Developers Console
• Naver: Naver Developers Console

글로벌 소셜 플랫폼

• Google: Google Cloud Console
• GitHub: GitHub Developer Settings

자세한 설정 방법은 각 provider의 README를 참조하세요:

• Kakao 설정 가이드
• LINE 설정 가이드
• Naver 설정 가이드
• Google 설정 가이드
• GitHub 설정 가이드

2. Keycloak 관리 콘솔 설정

1. Keycloak 관리 콘솔 로그인
2. Realm 선택
3. Identity Providers 메뉴로 이동
4. Add provider 드롭다운 클릭
5. 원하는 provider 선택 (Kakao, LINE, Naver, Google, 또는 GitHub)
6. Provider 설정 입력

3. Redirect URI 설정

각 provider는 다음 형식의 redirect URI를 설정해야 합니다:

https://your-keycloak-domain.com/realms/{realm}/broker/{provider}/endpoint

{provider}는 kakao, line, naver, google, 또는 github 중 하나입니다.

테스트 (Testing)

단위 테스트 (Unit Tests)

모든 단위 테스트 실행:

./gradlew test

특정 provider 테스트:

./gradlew :idps:idp-kakao:test
./gradlew :idps:idp-line:test
./gradlew :idps:idp-naver:test
./gradlew :idps:idp-google:test
./gradlew :idps:idp-github:test

통합 테스트 (Integration Tests)

Event Listener 모듈들은 TestContainers 기반 통합 테스트를 제공합니다:

통합 테스트 실행 (Docker 필요):

# Kafka 통합 테스트
./gradlew :events:event-listener-kafka:integrationTest

# RabbitMQ 통합 테스트
./gradlew :events:event-listener-rabbitmq:integrationTest

# Redis 통합 테스트
./gradlew :events:event-listener-redis:integrationTest

# NATS 통합 테스트
./gradlew :events:event-listener-nats:integrationTest

# MQTT 통합 테스트 (선택사항 - 구현 가능)
# ./gradlew :events:event-listener-mqtt:integrationTest

주의사항:

• 통합 테스트는 Docker가 실행 중이어야 합니다
• TestContainers가 자동으로 컨테이너를 시작/중지합니다
• CI/CD 파이프라인에서는 릴리즈 시에만 자동 실행됩니다
• 수동 실행 시: GitHub Actions → integration-tests 워크플로우 → "Run workflow" 클릭

테스트 커버리지

Identity Providers (단위 테스트):

• OAuth2 플로우 테스트
• 사용자 프로필 매핑 테스트
• 에러 처리 시나리오 테스트
• JSON 파싱 및 데이터 변환 테스트

Event Listeners (통합 테스트):

• 컨테이너 시작 및 연결 확인
• 메시지 발행/구독 테스트
• Keycloak Realm 설정 검증
• 성능 테스트 (메시지 처리량)
• Keycloak 이벤트 → 메시징 시스템 E2E 테스트

프로젝트 구조 (Project Structure)

sb-keycloak-exts/
├── .github/
│   └── workflows/         # GitHub Actions 워크플로우
│       ├── ci.yml         # CI 파이프라인
│       └── release.yml    # 릴리즈 자동화
├── build.gradle           # 루트 빌드 설정
├── gradle.properties      # Gradle 속성
├── settings.gradle        # 멀티 모듈 설정
└── idps/                  # Identity providers 모듈
    ├── build.gradle       # IDP 모듈 설정
    ├── idp-kakao/         # Kakao provider
    │   ├── src/
    │   │   ├── main/      # 소스 코드
    │   │   └── test/      # 테스트 코드
    │   └── README.md      # Kakao 설정 가이드
    ├── idp-line/          # LINE provider
    │   ├── src/
    │   │   ├── main/      # 소스 코드
    │   │   └── test/      # 테스트 코드
    │   └── README.md      # LINE 설정 가이드
    ├── idp-naver/         # Naver provider
    │   ├── src/
    │   │   ├── main/      # 소스 코드
    │   │   └── test/      # 테스트 코드
    │   └── README.md      # Naver 설정 가이드
    ├── idp-google/        # Google provider
    │   ├── src/
    │   │   ├── main/      # 소스 코드
    │   │   └── test/      # 테스트 코드
    │   └── README.md      # Google 설정 가이드
    └── idp-github/        # GitHub provider
        ├── src/
        │   ├── main/      # 소스 코드
        │   └── test/      # 테스트 코드
        └── README.md      # GitHub 설정 가이드

문제 해결 (Troubleshooting)

일반적인 문제

1. Provider가 Keycloak에 나타나지 않음

   • JAR 파일이 올바른 디렉토리에 있는지 확인
   • Keycloak 로그에서 로딩 오류 확인
   • shadowJar로 빌드했는지 확인

2. 인증 실패

   • Client ID와 Secret이 올바른지 확인
   • Redirect URI 설정 확인
   • 소셜 플랫폼에서 필요한 권한이 활성화되었는지 확인

중장기 개선 방향 (Future Improvements)

1. CI/CD 파이프라인 ✅ 완료

   • GitHub Actions 워크플로우 구성
   • 자동 테스트 및 배포
   • 다중 Java 버전 테스트 (17, 21)

2. 추가 IDP 구현 🔄 진행중

   • Google ✅ 완료
   • GitHub ✅ 완료
   • Discord (https://github.com/wadahiro/keycloak-discord)
   • Apple (https://github.com/klausbetz/apple-identity-provider-keycloak)
   • 공통 코드 추출하여 중복 제거

3. 이벤트 리스너 ✅ 완료

   • Kafka ✅
   • RabbitMQ ✅
   • NATS ✅
   • Redis ✅
   • MQTT ✅ NEW
   • AWS SNS/SQS ✅
   • Azure Service Bus/Event Grid ✅
   • Resilience patterns 완전 구현
   • Production-ready 품질

4. 보안 및 모니터링

   • 로깅 프레임워크 추가
   • 메트릭 수집 기능

5. 테마 지원

   • Keycloakify 통합 (https://www.keycloakify.dev/)
   • 한국어 UI 개선

버전 관리 (Versioning)

이 프로젝트는 Semantic Versioning을 따릅니다.

릴리즈 (Release)

릴리즈는 GitHub의 태그 기반으로 자동화되어 있습니다:

git tag v1.0.0
git push origin v1.0.0

태그 푸시 시 GitHub Actions가 자동으로:

• 빌드 및 테스트 실행
• Shadow JAR 생성
• GitHub Release 생성
• JAR 파일 업로드

라이선스 (License)

이 프로젝트는 Apache License 2.0으로 배포됩니다.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2025 ScriptonBasestar

기여하기 (Contributing)

기여를 환영합니다! Pull Request를 보내주세요.

참고 자료 (References)

• Keycloak Extensions
• Keycloak Server Developer Guide