Keycloak 소개

2024년 5월 15일 · 6 min read

Keycloak은 오픈소스 인증 및 권한 관리 솔루션으로, SSO(Single Sign-On) 및 다양한 보안 프로토콜(OAuth2, OpenID Connect 등)을 지원합니다.

기업 환경에서의 인증 및 권한 관리를 간소화할 수 있으며, 커스터마이징 옵션이 풍부해 다양한 요구 사항에 대응할 수 있습니다. 이 글에서는 Keycloak의 기본 개념, 설치 및 사용 방법을 소개하고, 추가로 활용할 수 있는 고급 기능들을 간단히 살펴보겠습니다.

Keycloak란 무엇인가? #

Keycloak은 Red Hat이 지원하는 오픈소스 인증 서버입니다. 주요 기능은 다음과 같습니다:

SSO(Single Sign-On): 한 번의 로그인으로 여러 애플리케이션 및 서비스에 접근 가능.
OAuth2 및 OpenID Connect 지원: 현대적인 인증 및 권한 부여 프로토콜을 기본적으로 지원.
LDAP 및 Active Directory 통합: 기업 내 기존 사용자 디렉토리와 연동 가능.
소셜 로그인: Google, Facebook, Twitter 등의 계정으로 로그인.
관리 UI 제공: 사용자가 친숙하게 접근할 수 있는 직관적인 웹 인터페이스.
확장성: 플러그인 개발을 통해 새로운 기능 추가 가능.

Keycloak 설치 및 기본 설정 #

Keycloak을 설치하는 방법에는 Docker를 사용하는 방법과 독립 실행형 배포 방식이 있습니다. 여기서는 Docker 기반 설치를 예로 들어 설명하겠습니다.

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

위 명령어는 Keycloak의 최신 버전을 설치하고 개발 모드로 실행합니다.

초기 설정

브라우저에서 http://localhost:8080으로 이동합니다.
초기 관리자 계정(admin/admin)으로 로그인합니다.
새로운 Realm을 생성하여 프로젝트별 인증 환경을 구성합니다.

Keycloak의 기본 구성 요소 #

Keycloak의 주요 구성 요소는 다음과 같습니다:

Realm: 인증 및 권한 관리를 위한 독립된 환경.
Clients: Keycloak을 사용하는 애플리케이션.
Users: 인증을 받는 최종 사용자.
Roles: 권한 수준을 정의하는 단위.
Groups: 사용자 관리를 위한 그룹화.

Keycloak으로 OAuth2 구현하기 #

OAuth2는 현대적인 애플리케이션에서 자주 사용되는 인증 및 권한 부여 프로토콜입니다. Keycloak은 OAuth2를 기본적으로 지원하며, REST API와 웹 애플리케이션에서 활용하기 쉽게 설정할 수 있습니다. 이 섹션에서는 OAuth2를 사용해 클라이언트 애플리케이션과 Keycloak을 연동하는 과정을 단계별로 설명합니다.

OAuth2의 기본 흐름

OAuth2를 이해하기 위해 기본적인 인증 흐름을 살펴보겠습니다:

사용자가 애플리케이션(Client)에서 로그인을 요청합니다.
애플리케이션은 Keycloak 인증 서버로 사용자를 리디렉션합니다.
사용자는 Keycloak에서 인증 정보를 입력하여 인증을 완료합니다.
Keycloak은 애플리케이션에 Access Token과 Refresh Token을 발급합니다.
애플리케이션은 Access Token을 이용해 리소스 서버(API)에 요청을 보냅니다.
리소스 서버는 Access Token을 검증한 후 요청을 처리합니다.

Keycloak에서 클라이언트 설정하기

OAuth2를 사용하려면 먼저 Keycloak에서 클라이언트를 생성하고 설정해야 합니다.

클라이언트 생성

Keycloak 관리 콘솔에 로그인합니다.
좌측 메뉴에서 Clients를 선택하고 Create를 클릭합니다.
Client ID에 클라이언트 이름을 입력합니다(예: my-app).
Client Protocol은 기본값으로 openid-connect를 선택합니다.
Root URL에 클라이언트 애플리케이션의 URL(예: http://localhost:8080)을 입력합니다.
설정을 저장합니다.

클라이언트 구성

생성한 클라이언트를 선택하고 Settings 탭에서 다음과 같이 설정합니다:
- Access Type: confidential로 설정(서버 간 통신을 위한 설정).
- Authorization Enabled: ON으로 설정(권한 부여 사용).
Credentials 탭으로 이동하여 Client Secret 값을 확인합니다. 이 값은 애플리케이션에서 Keycloak과 통신할 때 필요합니다.

Spring Boot 애플리케이션에 Keycloak 연동하기

Keycloak과 Spring Boot 애플리케이션을 연동하여 OAuth2 인증을 구현하는 방법을 살펴보겠습니다.

의존성 추가

Spring Boot 프로젝트의 pom.xml에 다음 의존성을 추가합니다:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-jose</artifactId>
</dependency>

애플리케이션 설정

application.yml 파일에 Keycloak과의 연동을 위한 설정을 추가합니다:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/realms/my-realm

리소스 서버 구현

Spring Security를 사용하여 REST API의 접근 권한을 설정합니다:

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer()
            .jwt();
    }
}

액세스 토큰 검증

Keycloak에서 발급된 Access Token을 통해 사용자의 권한을 검증할 수 있습니다.

Spring Security의 @PreAuthorize 어노테이션을 활용하여 권한 기반 접근 제어를 구현할 수 있습니다:

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/user")
    @PreAuthorize("hasRole('user')")
    public ResponseEntity<String> userEndpoint() {
        return ResponseEntity.ok("Hello, User!");
    }

    @GetMapping("/admin")
    @PreAuthorize("hasRole('admin')")
    public ResponseEntity<String> adminEndpoint() {
        return ResponseEntity.ok("Hello, Admin!");
    }
}

Postman을 사용한 테스트

Keycloak과 연동된 API를 테스트하려면 Postman을 사용하여 Access Token을 발급받고 요청을 보낼 수 있습니다.

1. Access Token 발급

Postman에서 새 요청을 생성합니다.
POST 요청으로 http://localhost:8080/realms/my-realm/protocol/openid-connect/token에 접근합니다.
Body에서 다음 정보를 추가합니다:
- grant_type: client_credentials
- client_id: 클라이언트 ID
- client_secret: 클라이언트 시크릿

2. API 요청

Access Token을 발급받은 후, 헤더에 다음과 같이 추가하여 API 요청을 보냅니다:

Authorization: Bearer <ACCESS_TOKEN>

Keycloak 보안 모범 사례 #

HTTPS 사용: 운영 환경에서는 항상 HTTPS를 활성화합니다.
관리자 계정 보호: 초기 관리자 계정의 비밀번호를 즉시 변경하세요.
세션 시간 제한 설정: 불필요한 세션 유지를 방지합니다.

이와 같은 방식으로 Keycloak을 활용하여 인증 및 권한 관리를 간소화할 수 있습니다.

결론 #

Keycloak에 대해 간단히 알아보았습니다. 사내 LDAP 통합이나 간단한 인증 서버 구축과 같은 요구 사항을 해결하기 위해 Keycloak은 탁월한 선택이 될 수 있습니다. 사용자 친화적인 관리 인터페이스와 폭넓은 기능은 복잡한 인증 및 권한 관리 작업을 단순화하며, 조직의 IT 환경에 쉽게 통합할 수 있는 유연성을 제공합니다.

특히 OAuth2, OpenID Connect와 같은 현대적인 인증 프로토콜을 기본적으로 지원하며, Google, Facebook 등 소셜 로그인을 손쉽게 설정할 수 있는 기능은 Keycloak을 더욱 매력적으로 만들어 줍니다. 또한, LDAP, Active Directory 등 기존 디렉토리 서비스와의 연동도 간단하여 기업 환경에서의 실용성을 증대시킵니다.

Keycloak은 활발히 유지 관리되고 있는 오픈소스 프로젝트로, 다른 솔루션들에 비해 안정성과 성숙도가 높은 편입니다. 이로 인해 중소규모 애플리케이션부터 대규모 엔터프라이즈 환경까지 다양한 규모의 프로젝트에서 신뢰할 수 있는 인증 시스템으로 자리 잡고 있습니다.

다음 글에서는 Keycloak을 활용해 각 상황에 맞는 구체적인 사용 방법과 설정 예제를 살펴보겠습니다. 로그인 화면 커스터마이징, 멀티테넌시 환경 구축, Kubernetes와의 통합 등 실질적인 활용 사례를 중심으로 더욱 깊이 있는 내용을 다룰 예정이니 많은 기대 바랍니다.