LIT-keycloak-overview

요약

Keycloak은 오픈소스 IAM(Identity and Access Management) 솔루션으로, 애플리케이션에 인증과 인가 기능을 최소한의 노력으로 추가할 수 있게 해준다. Red Hat의 JBoss 생태계에서 출발하여 현재는 CNCF Incubating 프로젝트로 자리잡았다. SSO, Identity Brokering, User Federation, Social Login 등 현대 애플리케이션에 필요한 인증 기능을 포괄적으로 제공하며, OAuth 2.0, OpenID Connect, SAML 2.0 등 표준 프로토콜을 지원한다. SPI 기반 아키텍처로 확장이 용이하고, Kubernetes Operator를 통한 클라우드 네이티브 배포와 고가용성 클러스터링을 지원한다.

핵심 포인트

Keycloak 정의와 역사

Keycloak은 SSO 기능을 갖춘 오픈소스 IAM 솔루션이다. Java로 작성되었으며 Apache License 2.0 하에 배포된다. 2014년 9월에 첫 정식 릴리스가 나왔고, 2026년 2월 기준 최신 안정 버전은 26.5.3이다. 약 12년의 역사를 가진 성숙한 프로젝트이다.

Red Hat/JBoss 배경

Keycloak은 Red Hat의 WildFly(구 JBoss) 커뮤니티 프로젝트로 시작되었다. 2016년에 Red Hat은 자사의 SSO 제품 기반을 PicketLink 프레임워크에서 Keycloak으로 전환했으며, PicketLink 코드베이스를 Keycloak에 병합했다. Red Hat은 Keycloak을 upstream으로 사용하여 상용 "Red Hat build of Keycloak" 제품을 제공한다. 이전의 Red Hat JBoss SSO 오픈소스 제품을 사실상 계승한 프로젝트이다.

CNCF Incubating 프로젝트

2023년 4월, Keycloak은 CNCF에 기증되어 incubating project로 합류했다. 이는 Keycloak이 클라우드 네이티브 생태계의 핵심 인증 인프라로 인정받았음을 의미한다. KubeCon 등 CNCF 주요 행사에 정기적으로 참여하고 있다.

핵심 기능

SSO (Single Sign-On) 사용자가 Keycloak에 한 번 로그인하면 연동된 모든 애플리케이션에 추가 로그인 없이 접근할 수 있다. 반대로 한 번 로그아웃하면 모든 애플리케이션에서 로그아웃된다. 애플리케이션은 로그인 폼이나 사용자 저장을 직접 구현할 필요가 없다.

Identity Brokering 외부 OpenID Connect 또는 SAML 2.0 Identity Provider를 통한 인증을 중개한다. Admin Console에서 설정만으로 외부 IdP를 연동할 수 있으며, 애플리케이션 코드 변경이 필요 없다.

User Federation LDAP, Active Directory 등 기존 사용자 디렉토리와 연결하여 기존 사용자 정보를 그대로 활용할 수 있다. 커스텀 프로바이더를 구현하면 관계형 데이터베이스 등 다른 저장소와도 연동 가능하다.

Social Login Google, Facebook, GitHub 등 소셜 네트워크를 통한 로그인을 Admin Console에서 설정만으로 추가할 수 있다. 코드 변경이 필요 없다.

OAuth 2.0 / OpenID Connect / SAML 지원 산업 표준 프로토콜을 기반으로 구축되어 있다. OAuth 2.0으로 인가, OpenID Connect로 인증, SAML 2.0으로 엔터프라이즈 환경의 SSO를 처리한다. 토큰 서비스 생성, 토큰 교환 등 고급 기능도 제공한다.

아키텍처 (Realm, Client, User, Role, Group, Identity Provider)

Keycloak의 아키텍처는 멀티테넌시를 핵심으로 설계되었다:

Realm: 사용자, 자격 증명, 역할, 그룹을 관리하는 독립적 네임스페이스. 각 Realm은 완전히 격리되어 있어 멀티테넌트 환경을 구현할 수 있다.
Client: 인증을 요청하는 애플리케이션 또는 서비스. 각 Client는 특정 Realm에 속한다.
User: 로그인 가능한 사용자 엔티티.
Role: 사용자의 역할을 정의. Realm 수준과 Client 수준의 역할이 구분된다.
Group: 사용자의 논리적 집합. 역할 매핑을 그룹 단위로 적용할 수 있다.
Identity Provider: 외부 인증 서비스. SAML 2.0, OIDC, 소셜 프로바이더 등을 지원한다.

Admin Console

웹 기반 관리 콘솔을 통해 Keycloak 서버의 모든 측면을 중앙에서 관리할 수 있다. Realm, Client, User, Role, Group 등의 구성과 Identity Brokering, User Federation, 인가 정책을 설정할 수 있다. 사용자를 위한 Account Management Console도 별도로 제공되어, 사용자가 스스로 프로필 업데이트, 비밀번호 변경, 2단계 인증 설정 등을 할 수 있다.

확장성 (SPI, Custom Providers)

Keycloak은 SPI(Service Provider Interface) 기반 아키텍처를 채택하여 높은 확장성을 제공한다. 개발자는 Custom Provider를 구현하여 User Storage, Authentication Flow, Event Listener, Protocol Mapper 등을 확장할 수 있다. 테마 커스터마이징을 통해 로그인 페이지, Admin Console, Account Console의 룩앤필을 변경할 수 있다. 비밀번호 정책도 커스터마이징이 가능하다.

고가용성/클러스터링

Keycloak은 프로덕션 환경을 위한 고가용성 아키텍처를 지원한다:

Single-cluster 배포: 단일 클러스터 내에서 여러 인스턴스를 운영하며, 여러 가용 영역(AZ)에 걸쳐 배포할 수 있다.
Multi-cluster 배포: 독립적인 Kubernetes 클러스터에 여러 Keycloak 배포를 연결하여 지역 간 고가용성을 확보할 수 있다.
분산 캐시: Infinispan을 사용한 분산 캐시로 세션 데이터를 인스턴스 간에 공유하고 성능을 향상시킨다.

Kubernetes 연동

Keycloak은 클라우드 네이티브 환경과의 통합을 적극적으로 지원한다:

Keycloak Operator: Kubernetes와 OpenShift에서 Keycloak 배포를 관리하는 전용 Operator를 제공한다.
Realm 자동 임포트, 롤링 업데이트, 커스텀 이미지 빌드 등을 Operator를 통해 자동화할 수 있다.
컨테이너 이미지(Docker/Podman)를 공식 제공하며, Getting Started 가이드에서 Docker, Podman, Kubernetes, OpenShift 배포를 모두 안내한다.
OpenTelemetry, Prometheus, Grafana 등 클라우드 네이티브 관찰성 스택과 통합된다.

주요 사용 사례

엔터프라이즈 SSO: 조직 내 여러 애플리케이션에 대한 통합 인증
마이크로서비스 인증: API Gateway와 연동하여 마이크로서비스 아키텍처의 중앙 인증 서버로 활용 (Apache APISIX, KrakenD, Traefik Hub 등과 통합 가이드 제공)
소셜 로그인 통합: 다양한 소셜 프로바이더를 통한 사용자 인증
레거시 시스템 통합: LDAP/AD User Federation으로 기존 사용자 디렉토리 활용
세밀한 인가: 역할 기반 접근 제어(RBAC)를 넘어선 정책 기반 세밀한 인가
MCP 인증: Model Context Protocol(MCP) 서버의 인가 서버로도 활용 가능 (최신 가이드 제공)

나의 생각

Keycloak은 인증/인가 영역에서 사실상의 오픈소스 표준으로 자리잡은 것으로 보인다. CNCF incubating 프로젝트로의 전환은 Red Hat 단독 관리에서 커뮤니티 중심 거버넌스로의 전환을 의미하며, 프로젝트의 장기적 안정성에 긍정적이다.

SPI 기반 아키텍처는 Keycloak의 큰 강점이다. 인증 플로우, 사용자 저장소, 이벤트 처리 등 거의 모든 영역을 커스텀 구현으로 교체할 수 있어, 특수한 요구사항이 있는 환경에서도 유연하게 대응할 수 있다.

마이크로서비스 아키텍처에서 Keycloak은 중앙 인증 서버 역할로 매우 적합하다. 각 서비스가 개별적으로 인증을 구현하는 대신 Keycloak에 위임함으로써 인증 로직의 중복을 제거하고 일관된 보안 정책을 적용할 수 있다. mTLS와 결합하면 서비스 간 통신 보안과 사용자 인증을 모두 체계적으로 관리할 수 있을 것이다.

Kubernetes Operator 지원과 Quarkus 기반으로의 전환(WildFly에서 마이그레이션)은 클라우드 네이티브 환경에 대한 적극적인 적응을 보여준다. MCP 서버 인가 지원 같은 최신 트렌드 반영도 프로젝트의 활발한 발전을 보여준다.

gonnux.com