Spring Boot와 Keycloak으로 간단한 인증 시스템 구현하기: 실습으로 배우는 OAuth2와 SSO

Keycloak이란 무엇인가?

Keycloak은 오픈 소스 기반의 IAM(Identity and Access Management) 솔루션으로, 사용자 인증 및 권한 부여를 쉽게 관리할 수 있도록 해줍니다. Keycloak은 기업에서 자주 사용되는 OAuth2.0, OpenID Connect, SAML과 같은 표준 프로토콜을 지원하며, 이를 통해 다양한 애플리케이션에 대해 **Single Sign-On(SSO)**을 구현할 수 있습니다. 이를 통해 여러 애플리케이션에 대해 한 번의 로그인으로 인증을 처리할 수 있습니다.

Keycloak의 주요 특징

1. SSO 지원: 한 번의 로그인으로 여러 애플리케이션에 접근 가능.
2. OAuth2 및 OpenID Connect 지원: 표준 프로토콜 기반 인증 및 권한 부여 제공.
3. LDAP 및 Active Directory 연동: 기존 디렉터리 서비스와 손쉽게 통합 가능.
4. 관리자 UI 제공: 사용자 및 권한을 쉽게 관리할 수 있는 직관적인 관리자 콘솔 제공.
5. 확장성: 확장 가능한 클러스터 구성으로 대규모 애플리케이션 환경에 적합.

반응형

Spring Boot와 Keycloak 연동하여 인증 구현하기

Spring Boot와 Keycloak을 연동하여 OAuth2 기반의 인증을 처리하는 간단한 예제를 만들어 보겠습니다. 이 예제에서는 Keycloak을 사용하여 사용자 인증을 처리하고, Spring Security를 통해 인증된 사용자만 접근 가능한 API를 제공합니다.

프로젝트 설정

1. Gradle 프로젝트 생성

Spring Initializr에서 새로운 Gradle 기반의 Spring Boot 프로젝트를 생성합니다. 다음과 같은 설정으로 프로젝트를 구성하세요.

• Project: Gradle Project
• Language: Java
• Spring Boot: 3.x.x
• Dependencies: Spring Web, Spring Security, Spring Boot OAuth2 Resource Server, Keycloak Spring Boot Adapter

2. Gradle 설정 (build.gradle)

다음은 build.gradle 파일에 필요한 의존성을 추가한 예시입니다.

plugins {
    id 'org.springframework.boot' version '3.1.0'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'java'
}

group = 'com.example'
version = '1.0.0'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
    implementation 'org.keycloak:keycloak-spring-boot-starter:21.0.0'
    implementation 'org.keycloak:keycloak-spring-security-adapter:21.0.0'
    implementation 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

test {
    useJUnitPlatform()
}

Keycloak 설정

1. Keycloak 서버 설치 및 실행

• Keycloak 서버를 로컬에서 실행하거나, Docker를 이용해 설치할 수 있습니다.

Docker를 이용해 Keycloak을 실행하려면 다음 명령어를 사용합니다

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

Keycloak이 실행된 후, http://localhost:8080으로 접근하여 Keycloak 관리 콘솔에 로그인합니다.

2. Realm 및 Client 설정

1. Realm 생성: Keycloak 관리자 콘솔에서 새로운 Realm을 생성합니다. 예를 들어, "spring-boot-realm"이라고 명명할 수 있습니다.
2. Client 생성: Realm에서 새로운 Client를 생성합니다.
   • Client ID: spring-boot-client
   • Client Protocol: openid-connect
   • Access Type: confidential
   • Redirect URI: http://localhost:8080/*

생성 후 Credentials 탭에서 Client Secret을 복사해 둡니다.

Spring Boot 설정

1. application.yml 설정

src/main/resources/application.yml 파일에 Keycloak과 연동하기 위한 설정을 추가합니다.

server:
  port: 8080

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

keycloak:
  realm: spring-boot-realm
  auth-server-url: http://localhost:8080
  resource: spring-boot-client
  credentials:
    secret: <YOUR_CLIENT_SECRET>
  principal-attribute: preferred_username

위의 secret에는 Keycloak 클라이언트 생성 시 복사한 Client Secret을 입력합니다.

2. Security 설정 클래스

Spring Security를 설정하여 인증된 사용자만 특정 경로에 접근할 수 있도록 합니다.

package com.example.keycloakdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/public").permitAll()
                .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer()
                .jwt();
        return http.build();
    }
}

위 설정에서는 /public 경로는 인증 없이 접근할 수 있으며, 그 외의 경로는 인증된 사용자만 접근할 수 있도록 설정하였습니다.

3. Controller 구현

Keycloak 인증을 적용한 REST API를 구현합니다.

package com.example.keycloakdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

    @GetMapping("/public")
    public String publicEndpoint() {
        return "This is a public endpoint. No authentication required.";
    }

    @GetMapping("/private")
    public String privateEndpoint() {
        return "This is a private endpoint. Authentication required.";
    }
}

/api/public은 누구나 접근할 수 있는 공개 엔드포인트이며, /api/private는 인증된 사용자만 접근할 수 있는 보호된 엔드포인트입니다.

728x90

이제 Spring Boot와 Keycloak을 연동하여 OAuth2 기반 인증 시스템을 구축하는 방법을 알게 되었습니다. Keycloak은 다양한 표준 프로토콜을 지원하고, 확장성과 유연성이 뛰어나기 때문에 대규모 인증 시스템을 구현할 때 매우 유용합니다. 또한, Spring Security와 Keycloak을 결합하면 손쉽게 SSO 및 인증/권한 관리를 구현할 수 있어, 빠르고 안전한 인증 시스템을 구축할 수 있습니다.