Keycloak 시작하기 - 오픈소스 IAM 솔루션 완벽 가이드

Keycloak이란?

Keycloak은 Red Hat에서 개발한 오픈소스 Identity and Access Management (IAM) 솔루션입니다. 최신 애플리케이션과 서비스를 위한 인증 및 권한 부여 기능을 제공하며, Single Sign-On (SSO), 소셜 로그인, 사용자 페더레이션 등 다양한 기능을 지원합니다.

주요 특징

1. Single Sign-On (SSO)

• 한 번의 로그인으로 여러 애플리케이션 접근 가능
• SAML 2.0, OpenID Connect 프로토콜 지원
• 세션 관리 및 로그아웃 기능

2. 표준 프로토콜 지원

• OpenID Connect: OAuth 2.0 기반의 인증 레이어
• OAuth 2.0: 권한 부여 프레임워크
• SAML 2.0: 엔터프라이즈 SSO 표준

3. 소셜 로그인

• Google, Facebook, GitHub 등 주요 소셜 플랫폼 연동
• 커스텀 Identity Provider 추가 가능

4. 사용자 관리

• 사용자 등록 및 프로필 관리
• 비밀번호 정책 설정
• 2단계 인증 (2FA/MFA) 지원

Keycloak 설치하기

Docker를 이용한 빠른 시작

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start-dev

접속 및 초기 설정

1. 브라우저에서 http://localhost:8080 접속
2. Administration Console 클릭
3. admin/admin으로 로그인
4. 새로운 Realm 생성

기본 개념

Realm

• 사용자, 자격 증명, 역할, 그룹을 관리하는 독립된 공간
• 각 Realm은 완전히 격리된 환경

Client

• Keycloak의 보호를 받는 애플리케이션
• 웹 앱, 모바일 앱, REST API 등

Role

• 사용자 권한을 정의
• Realm Role과 Client Role로 구분

User Federation

• LDAP, Active Directory 등 기존 사용자 저장소와 연동

실제 활용 예제

Spring Boot 애플리케이션 연동

// application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: my-app
            client-secret: secret
            scope: openid, profile, email
        provider:
          keycloak:
            issuer-uri: http://localhost:8080/realms/myrealm

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login();
        return http.build();
    }
}

Keycloak의 장점

1. 완전한 오픈소스: 무료로 사용 가능하며 커뮤니티 활성화
2. 표준 준수: 업계 표준 프로토콜 지원으로 이식성 높음
3. 확장 가능: 커스텀 인증 로직, 테마, 프로바이더 추가 가능
4. 관리 편의성: 직관적인 관리 콘솔 제공
5. 고가용성: 클러스터링 지원으로 엔터프라이즈 환경에 적합

주의사항

• 프로덕션 환경에서는 반드시 HTTPS 사용
• 기본 admin 계정의 비밀번호는 즉시 변경
• 정기적인 보안 업데이트 적용 필요
• 데이터베이스는 별도로 구성 권장 (내장 H2는 개발용)

결론

Keycloak은 현대적인 애플리케이션에서 인증/인가를 구현할 때 매우 유용한 도구입니다. 복잡한 보안 로직을 직접 구현하는 대신, Keycloak을 활용하면 빠르고 안전하게 사용자 인증 시스템을 구축할 수 있습니다.

특히 마이크로서비스 아키텍처나 여러 애플리케이션을 운영하는 환경에서 SSO 구현이 필요하다면, Keycloak은 최고의 선택지 중 하나입니다.