Spring Boot 4와 Keycloak 연동, JWT 인증·역할 기반 접근 완전 정복
Spring Boot 4에 Keycloak을 결합해 JWT 기반 인증과 세밀한 역할 제어를 구현하는 방법을 단계별로 풀어내며, 실무 적용 시 꼭 알아야 할 장단점과 법적 고려사항을 한눈에 정리했습니다.
개요
많은 기업이 마이크로서비스 아키텍처로 전환하면서, 분산된 시스템 간에 일관된 인증·인가 체계를 구축하는 것이 큰 과제로 떠올랐습니다. 특히 Spring Boot 4와 같은 최신 프레임워크를 사용하면서도, 외부 IdP(Identity Provider)와의 연동을 손쉽게 처리하려면 Keycloak과 같은 오픈소스 IAM 솔루션이 필수적입니다. 하지만 실제 프로젝트에 적용하려면 JWT 토큰 발급, 토큰 검증, 역할 기반 접근 제어(RBAC)를 어떻게 설계하고 구현해야 하는지에 대한 구체적인 가이드가 부족합니다.
편집자 의견
Spring 생태계는 이미 Spring Security라는 강력한 보안 모듈을 제공하지만, 이를 Keycloak과 결합하면 인증 서버와 리소스 서버를 명확히 분리할 수 있어 확장성과 유지보수성이 크게 향상됩니다. 특히 JWT를 활용하면 토큰 자체에 사용자 권한 정보를 담아 stateless하게 서비스를 운영할 수 있기 때문에, 클라우드 네이티브 환경에 최적화된 구조라 할 수 있습니다.
개인적인 관점
저는 최근 한 핀테크 스타트업 프로젝트에서 Spring Boot 4와 Keycloak을 연동해 보았습니다. 초기 설정에 약간의 시행착오가 있었지만, spring-boot-starter-oauth2-resource-server와 spring-boot-starter-oauth2-client 의존성을 활용하면 대부분의 복잡한 로직을 자동화할 수 있었습니다. 특히 @PreAuthorize 어노테이션을 이용해 메서드 레벨에서 역할을 검증하는 방식은 코드 가독성을 크게 높여 주었습니다.
기술 구현 단계
아래는 Spring Boot 4 프로젝트에 Keycloak을 연결하고 JWT 기반 인증·인가를 구현하는 핵심 단계입니다.
pom.xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-spring-boot-starter</artifactId>
<version>22.0.5</version>
</dependency>
1️⃣ Keycloak Realm 및 Client 설정
Keycloak 관리 콘솔에서 새로운 Realm을 만들고, Spring Boot 애플리케이션을 confidential 타입 클라이언트로 등록합니다. client-id, client-secret, redirect-uri 등을 정확히 입력하고, Access Type을 confidential 로 지정합니다.
2️⃣ application.yml에 보안 설정 추가
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://keycloak.example.com/realms/myrealm
jwk-set-uri: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs
3️⃣ SecurityFilterChain 정의 – 최신 Spring Security는 Java Config 기반으로 @Bean 메서드 하나만으로 충분합니다.
@Configuration
public class SecurityConfig {
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.csrf(csrf -> csrf.disable())
.authorizeHttpRequests(auth -> auth
.requestMatchers("/public/**").permitAll()
.requestMatchers("/admin/**").hasRole("ADMIN")
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2.jwt());
return http.build();
}
}
4️⃣ 역할 매핑 – Keycloak에서 정의한 역할을 Spring Security의 ROLE_ 프리픽스로 매핑하려면 JwtAuthenticationConverter를 커스터마이징합니다.
@Bean
JwtAuthenticationConverter jwtAuthenticationConverter() {
JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
grantedAuthoritiesConverter.setAuthorityPrefix("ROLE_");
grantedAuthoritiesConverter.setAuthoritiesClaimName("realm_access");
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
return converter;
}
위 과정을 마치면 /admin/** 경로는 ADMIN 역할을 가진 사용자만 접근할 수 있게 됩니다.
기술적 장단점
- 장점
- Stateless 구조로 확장성이 뛰어나며, 세션 관리 비용이 감소한다.
- Keycloak이 제공하는 중앙 집중식 사용자·역할 관리로 운영 효율성이 높다.
- Spring Security와의 자연스러운 통합으로 기존 코드베이스를 크게 변경하지 않아도 된다.
- 단점
- JWT 토큰이 커지면 네트워크 트래픽이 증가하고, 캐시 전략을 별도로 설계해야 한다.
- Keycloak 서버 자체가 단일 장애점이 될 수 있어 HA 구성을 반드시 고려해야 한다.
- 역할이 복잡해질 경우 토큰 클레임이 과도하게 늘어나 관리가 어려워진다.
주요 기능 장단점
- Role-Based Access Control (RBAC)
- Keycloak의 Realm‑Level 역할과 클라이언트‑Level 역할을 자유롭게 조합 가능.
- 하지만 역할 계층이 깊어질수록 정책 정의가 복잡해진다.
- Token Introspection
- JWT 자체 검증 외에 Keycloak에 토큰 유효성을 확인할 수 있어 보안성이 강화된다.
- 추가 호출이 발생해 응답 지연이 발생할 수 있다.
- Dynamic Client Registration
- 새로운 마이크로서비스를 빠르게 등록하고 권한을 부여할 수 있다.
- 자동 등록이 보안 정책에 따라 제한될 수 있다.
법·정책 해석
JWT 토큰에는 사용자 식별자와 권한 정보가 평문으로 포함되므로, 개인정보보호법 및 GDPR 등에서 요구하는 최소 데이터 원칙(minimum data principle)을 준수해야 합니다. 토큰에 포함되는 클레임은 반드시 비식별화된 형태로 설계하고, 토큰 유효기간을 짧게 설정해 노출 위험을 최소화합니다. 또한, Keycloak 로그 및 감사 로그를 별도 저장해 데이터 접근 기록을 남겨야 규제 대응이 용이합니다.
실제 적용 사례
한 전자상거래 기업은 Spring Boot 4 기반 주문 처리 서비스와 재고 관리 서비스에 각각 독립적인 리소스 서버를 두고, 중앙 인증 서버로 Keycloak을 도입했습니다. JWT 토큰을 활용해 마이크로서비스 간 호출 시 별도 세션을 유지하지 않아도 되었으며, 역할 기반 정책을 통해 ORDER_MANAGER와 INVENTORY_ADMIN이 각각 접근 가능한 API를 명확히 구분했습니다. 결과적으로 서비스 간 인증 지연이 30% 감소하고, 보안 사고 발생률이 현저히 낮아졌다고 보고했습니다.
실전 가이드: 단계별 적용 방법
- Keycloak 설치 및 초기 설정 – Docker Compose 혹은 Helm Chart를 이용해 HA 클러스터를 구축한다.
- Realm·Client·Role 정의 – 비즈니스 도메인에 맞는 역할을 설계하고, 클라이언트에 필요한 리다이렉트 URI를 등록한다.
- Spring Boot 프로젝트에 의존성 추가 – 위에서 제시한
pom.xml의존성을 포함한다. - application.yml에 Issuer 및 JWK 설정 – Keycloak의
issuer-uri와jwk-set-uri를 정확히 입력한다. - SecurityFilterChain 커스터마이징 – 경로별 접근 제어와 JWT 검증 로직을 구현한다.
- JwtAuthenticationConverter 로 역할 매핑 – Keycloak의
realm_access.roles를 Spring Security 권한으로 변환한다. - 테스트 및 검증 – Postman 혹은 curl 로 토큰을 발급받아 보호된 엔드포인트에 접근해 정상 동작을 확인한다.
- CI/CD 파이프라인에 보안 검사 추가 – 토큰 서명 검증, 역할 정책 검증 스크립트를 자동화한다.
- 운영 모니터링 – Keycloak의 이벤트 로그와 Spring Boot의 보안 로그를 ELK 스택에 연동해 실시간 감시한다.
FAQ
- Q: JWT 토큰을 탈취당하면 어떻게 대응하나요?
A: 토큰 유효기간을 짧게 설정하고, Refresh Token을 별도로 관리합니다. 또한, 토큰 재발급 시 IP·User-Agent 검증을 추가해 비정상적인 재발급을 차단합니다. - Q: Keycloak과 Spring Security 버전 호환성은 어떻게 확인하나요?
A: 공식 Spring Boot 릴리즈 노트와 Keycloak Spring Boot Adapter 문서를 교차 검증하고, Maven 의존성 트리를 확인해 충돌을 방지합니다. - Q: 역할이 동적으로 변할 때 토큰을 즉시 반영할 수 있나요?
A: JWT 자체는 불변이므로, 역할 변경 시 기존 토큰은 만료될 때까지 유효합니다. 즉시 반영이 필요하면Token Introspection엔드포인트를 활용해 실시간 검증을 수행합니다.
결론 및 액션 아이템
Spring Boot 4와 Keycloak을 결합하면 인증·인가를 중앙 집중식으로 관리하면서도, JWT 기반의 무상태 아키텍처를 구현할 수 있습니다. 지금 바로 적용하고 싶다면 다음 세 가지 액션을 실행하세요.
- 프로젝트에
spring-boot-starter-oauth2-resource-server와keycloak-spring-boot-starter를 추가하고,application.yml에 Issuer URI를 설정한다. - Keycloak 콘솔에서 Realm·Client·Role을 정의하고,
client-secret을 안전하게 보관한다. - SecurityFilterChain과 JwtAuthenticationConverter를 구현해 경로별 접근 정책을 적용하고, CI 파이프라인에 보안 테스트를 포함한다.
위 단계들을 차근히 수행하면, 복잡한 보안 로직을 최소화하면서도 기업 수준의 인증·인가 체계를 빠르게 구축할 수 있습니다.
관련 글 추천
- https://infobuza.com/2026/04/08/20260408-5tr5fe/
- https://infobuza.com/2026/04/08/20260408-6tlj2m/
지금 바로 시작할 수 있는 실무 액션
- 현재 팀의 AI 활용 범위와 검증 절차를 먼저 문서화합니다.
- 작은 파일럿 프로젝트로 KPI를 정하고 2~4주 단위로 검증합니다.
- 보안, 품질, 리뷰 기준을 자동화 도구와 함께 연결합니다.
