Keycloak 소개

Keycloak 소개

오픈소스 기반의 IAM(Identity and Access Management) 솔루션으로, 사용자 인증과 권한 관리를 통합적으로 수행할 수 있는 플랫폼입니다.

OAuth 2.0, OpenID Connect, SAML 등 표준 인증 프로토콜을 지원하며, 별도의 복잡한 개발 없이도 안전하고 확장 가능한 인증 환경을 구축할 

수 있습니다. 또한 LDAP, Active Directory와 같은 외부 사용자 디렉터리와 연동이 가능하며, 기업 내 여러 애플리케이션에서 Single Sign-

On(SSO) 환경을 손쉽게 구현할 수 있는 장점이 있습니다.

[Keycloak이 제공하는 서비스]

1. 표준화된 인증체계 제공
Keycloak은 자체 사용자 DB뿐만 아니라, OAuth2 / OpenID Connect 표준 기반 토큰 방식을 사용하여 인증을 처리합니다.

이를 통해 애플리케이션은 인증 로직을 직접 구현할 필요 없이, Keycloak이 발급하는 Access Token, Refresh Token, ID Token을 이용해 

보안성과 일관성을 유지할 수 있습니다.

2. 중앙집중식 사용자 및 권한관리
Keycloak은 사용자, 그룹, 역할(Role) 등의 권한 정보를 중앙에서 통합 관리합니다. 이를 통해 조직 내 여러 시스템이 동일한 사용자 정책을 공유할

 수 있으며, 관리자는 한 곳에서 모든 사용자의 접근 권한을 제어할 수 있습니다. 이는 시스템이 많아질수록 운영 효율성과 보안 통제력을 크게 

높여준다는 장점이 있습니다.

3. Single Sign-On(SSO) 지원
여러 애플리케이션 간에 한 번 로그인으로 모든 서비스에 접근할 수 있는 SSO 기능을 기본 제공합니다.

4. 외부 인증 연동 및 소셜 로그인
Keycloak은 Google, GitHub, Facebook과 같은 소셜 로그인뿐 아니라 LDAP, Active Directory 등의 기업용 인증 서버와도 쉽게 연동할 수 

있습니다. 이를 통해 기존 인프라와의 호환성을 유지하면서도 현대적인 인증 방식을 도입할 수 있습니다.

5. 보안 강화 기능 내장
Keycloak은 기본적으로 MFA(다단계 인증), 세션 만료 관리, 비밀번호 정책, 브루트포스 방어 기능을 제공합니다.

[보안기능 상세]

1. MFA (Multi-Factor Authentication, 다단계 인증)

• 사용자가 로그인할 때 두 가지 이상의 인증 수단을 요구하는 방식입니다.
  예: 비밀번호 + OTP(일회용 인증코드) 조합.
• 비밀번호가 유출되더라도, **두 번째 인증 단계(예: 휴대폰 앱, 이메일 코드)**가 있어
  무단 접근을 효과적으로 차단할 수 있습니다.

2. 세션 만료(Session Expiration) 관리

• 사용자가 로그인한 상태(세션)가 일정 시간이 지나면 자동으로 종료되도록 설정하는 기능입니다.
• 장시간 로그인 상태를 방치해도, 세션 만료 후 재로그인이 필요하게 하여
  계정 도용 및 세션 하이재킹 공격을 방지합니다.

3. 비밀번호 정책 (Password Policy)

• Keycloak은 비밀번호 복잡도, 길이, 변경 주기, 재사용 금지 등을 설정할 수 있는 정책 기능을 제공합니다.
• 예를 들어 “최소 8자 이상, 대문자·특수문자 포함” 같은 규칙을 적용해
  약한 비밀번호로 인한 보안 위험을 줄입니다.

4. 브루트포스(Brute Force) 방어

• 공격자가 여러 번 로그인 시도를 반복하여 비밀번호를 알아내는 것을 방지하는 기능입니다.
• Keycloak은 연속 로그인 실패 시 계정을 잠그거나,
  일정 시간 동안 재시도를 제한하는 기능을 제공합니다.
• 이를 통해 무차별 대입 공격을 사전에 차단합니다.

[Keycloak의 인증 흐름 예시]

[Keycloak 인증 방식]

기본적으로 토큰 기반 인증(Token-based Authentication) 방식을 사용합니다.
사용자가 로그인하면 Keycloak은 Access Token, Refresh Token, ID Token을 발급하며,
애플리케이션은 이 토큰을 이용해 사용자의 신원을 검증합니다.

1. 사용자가 클라이언트(웹/앱)에 로그인 요청
2. Keycloak 로그인 화면에서 인증 수행
3. 인증 성공 시 Keycloak이 토큰을 발급
4. 애플리케이션은 토큰을 받아 사용자의 접근 권한을 확인

이 과정에서 토큰은 표준 프로토콜(OAuth2, OIDC)을 기반으로 하므로, 다른 서비스나 시스템과의 연동도 용이합니다.
즉, Keycloak은 “직접 로그인 기능을 구현하지 않아도 되는 표준 인증 게이트웨이” 역할을 합니다.

[Keycloak 한계 및 단점]

Keycloak은 강력한 기능과 표준 기반 구조를 제공하지만, 모든 환경에 완벽히 맞는 해결책은 아닙니다.
특히 커스터마이징이나 운영 측면에서 몇 가지 제약과 고려사항이 존재하는데,

• 커스터마이징 제약
  Keycloak은 표준 프로토콜(OAuth2, OpenID Connect, SAML)에 맞추어 동작하기 때문에,
  인증 흐름이나 토큰 구조를 임의로 변경하기 어렵다는 단점이 있습니다.
  예를 들어, 발급되는 토큰의 형식을 자체적으로 정의하거나 특정 로직을 추가하려면
  Java 기반의 SPI(Service Provider Interface) 확장 개발이 필요합니다.
  
  
• 복잡한 설정 및 운영 부담
  Keycloak은 다양한 기능을 제공하는 만큼, 초기 설정이 복잡하며,
  Realm, Client, Role, Scope 등 개념을 이해하고 올바르게 구성해야 합니다.
  대규모 시스템에서는 이를 체계적으로 관리하지 않으면 혼란이 발생하기 쉽다고 합니다.
  또한 버전 업그레이드 시 설정 충돌이나 커스터마이징한 기능이 깨질 위험이 존재하기 때문에 충분한 고려 후 구축해야 합니다.
  
  
• 유지보수 및 버전 호환성 문제
  Keycloak은 오픈소스 프로젝트로 꾸준히 업데이트되지만, 새 버전에서 API나 설정 방식이 변경될 경우 기존 시스템과의 호환성 문제가 발생할 수 있습니다. 특히 자체적으로 커스터마이징한 확장 모듈이 있을 경우, 업그레이드 시 수정 작업이 필수적입니다.

[연동 방법]

KeyCloak 이 인증 처리, 토큰 검증, 세션 관리를 자동으로 해주려면 Maven이나 Gradle에 Keycloak 관련 의존성(Dependency)을 

추가해야 합니다.

[Gradle]
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.keycloak:keycloak-spring-boot-starter:24.0.3'
// (선택) 관리자 API 사용 시
implementation 'org.keycloak:keycloak-admin-client:24.0.3'

[일반 API 사용시 연동 API (사용자 인증용 설정)]

사용자가 웹/앱을 통해 로그인하고,
Keycloak으로부터 Access Token / ID Token을 받아 인증 처리하는 방식입니다.
(인증방식: OIDC Redirect Flow)

[yml]

keycloak:

  auth-server-url: http://localhost:8080/auth  # Keycloak 서버 URL

  realm: myrealm # 인증이 수행될 영역 이름

  resource: myclient # Keycloak에 등록된 클라이언트 ID

  credentials:

    secret: 1234-5678-90ab-cdef # 해당 클라이언트의 비밀키

  bearer-only: false   # 클라이언트가 직접 로그인 플로우를 수행

ssl-required: external

[일반 API 호출 엔드포인트 정리]

API들은 대부분 /realms/{realm}/protocol/openid-connect/ 아래에 존재합니다.

[Admin API 사용 시 (관리자 접근용 설정)]

Keycloak 서버의 사용자·그룹·클라이언트 관리 작업을 수행하기 위해
서버 측에서 관리자 권한으로 REST API를 호출합니다.

(인증방식: Direct Grant / Admin Token)

[yml]

keycloak:

  server-url: http://localhost:8080/auth

  realm: master # 관리 작업이 수행되는 기본 Realm

  client-id: admin-cli # Keycloak 기본 관리자 클라이언트

  username: admin # 관리자 계정 정보

  password: admin123

[Admin API 호출 시 엔드포인트 정리]

Keycloak은 표준화, 보안성, 확장성 측면에서는 매우 강력하지만, 자유도, 커스터마이징, 운영 편의성 면에서는 일정한 제약이 존재합니다.

따라서 단순한 사용자 인증 시스템이 아니라, 조직 전체의 IAM 체계 구축이 필요한 환경에서 가장 큰 효과를 발휘하므로 소규모 프로젝트나 

인증 로직을 세밀히 제어해야 하는 서비스라면, Keycloak 대신 경량화된 자체 인증 서버를 고려하는 것도 좋은 방법일 수 있습니다.

                                                                                                                                                                                                                             ⭐발표자 : 남상엽님