251117_02_ENH : Security, Swagger, MVC 기본 설정 추가

This commit is contained in:
2025-11-17 15:33:48 +09:00
parent 9f87ce586b
commit e5501e1542
14 changed files with 995 additions and 380 deletions

859
README.md

File diff suppressed because it is too large Load Diff

View File

@@ -4,7 +4,7 @@ plugins {
}
//버전 변경은 여기서
def commonVer = "1.0.4"
def commonVer = "1.0.15"
group = 'com.kri.common'
version = commonVer
@@ -35,9 +35,14 @@ dependencies {
// Security Core
api 'org.springframework.security:spring-security-core'
// ✅ HttpSecurity, SecurityFilterChain, WebSecurityCustomizer 등 들어있는 모듈들
compileOnly 'org.springframework.security:spring-security-config'
compileOnly 'org.springframework.security:spring-security-web'
// Swagger / OpenAPI 어노테이션 (@Schema 등) - 컴파일용
compileOnly 'io.swagger.core.v3:swagger-annotations:2.2.25'
compileOnly 'io.swagger.core.v3:swagger-models:2.2.25'
compileOnly 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
// Lombok
compileOnly 'org.projectlombok:lombok'

View File

@@ -0,0 +1,69 @@
package com.kri.common.security;
import com.kri.common.auth.apikey.ApiKeyProperties;
import com.kri.common.auth.apikey.ApiKeyUserClaimsProvider;
import com.kri.common.auth.jwt.JwtService;
import com.kri.common.auth.jwt.JwtUserClaimsDto;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.Optional;
@RequiredArgsConstructor
public class ApiKeyAuthFilter extends OncePerRequestFilter {
private final ApiKeyProperties properties;
private final ApiKeyUserClaimsProvider userClaimsProvider;
private final JwtService jwtService; // DTO -> Authentication 변환 용도
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain
) throws ServletException, IOException {
// 기능이 꺼져 있으면 바로 패스
if (!properties.isEnabled()) {
filterChain.doFilter(request, response);
return;
}
// 이미 다른 필터에서 Authentication 을 세팅했다면 건너뜀
if (SecurityContextHolder.getContext().getAuthentication() != null) {
filterChain.doFilter(request, response);
return;
}
String headerName = properties.getHeaderName();
String apiKey = request.getHeader(headerName);
if (apiKey == null || apiKey.isBlank()) {
filterChain.doFilter(request, response);
return;
}
// 서비스 쪽 구현체에서 apiKey -> JwtUserClaimsDto 매핑
Optional<JwtUserClaimsDto> userOpt = userClaimsProvider.findUserByApiKey(apiKey);
if (userOpt.isPresent()) {
JwtUserClaimsDto dto = userOpt.get();
// 공통 JwtService 가 제공하는 DTO -> Authentication 변환 사용
Authentication auth = jwtService.toAuthentication(dto);
SecurityContextHolder.getContext().setAuthentication(auth);
} else {
// 유효하지 않은 API-Key → 그냥 Authentication 세팅 안 함
// 이후 anyRequest().authenticated() 에서 401/403 처리
}
filterChain.doFilter(request, response);
}
}

View File

@@ -0,0 +1,48 @@
package com.kri.common.security;
import com.kri.common.auth.jwt.JwtService;
import io.jsonwebtoken.JwtException;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {
private final JwtService jwtService;
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain
) throws ServletException, IOException {
// 이미 인증이 있다면 건너뜀 (API-Key 필터 등에서 먼저 세팅했을 수 있음)
if (SecurityContextHolder.getContext().getAuthentication() == null) {
String header = request.getHeader("Authorization");
if (header != null && header.startsWith("Bearer ")) {
String token = header.substring("Bearer ".length());
try {
// ★ 오직 "정상 JWT" 만 처리
Authentication auth = jwtService.toAuthentication(token);
SecurityContextHolder.getContext().setAuthentication(auth);
} catch (JwtException ex) {
// 여기서 바로 401 내고 끊고 싶으면 이렇게 할 수도 있고:
// response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
// return;
//
// 기본값은 "인증 세팅 안 함" + 나머지 필터 → 결국 anyRequest().authenticated()에서 401 떨어짐
}
}
}
filterChain.doFilter(request, response);
}
}

View File

@@ -0,0 +1,87 @@
package com.kri.common.security;
import com.kri.common.auth.apikey.ApiKeyAuthFilter;
import com.kri.common.auth.apikey.ApiKeyProperties;
import com.kri.common.auth.apikey.ApiKeyUserClaimsProvider;
import com.kri.common.auth.jwt.JwtProperties;
import com.kri.common.auth.jwt.JwtService;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
@AutoConfiguration(before = SecurityAutoConfiguration.class)
@EnableConfigurationProperties({KriSecurityProperties.class, JwtProperties.class})
@ConditionalOnProperty(prefix = "kri.security", name = "enabled", havingValue = "true", matchIfMissing = true)
@EnableMethodSecurity(
jsr250Enabled = true,
prePostEnabled = true
)
@RequiredArgsConstructor
public class KriSecurityAutoConfiguration {
private final KriSecurityProperties securityProperties;
private final JwtProperties jwtProperties;
@Bean
@ConditionalOnMissingBean
public JwtService jwtService(JwtProperties properties) {
return new JwtService(properties);
}
@Bean
@ConditionalOnMissingBean
public JwtAuthenticationFilter jwtAuthenticationFilter(JwtService jwtService) {
return new JwtAuthenticationFilter(jwtService);
}
/**
* 서비스에서 SecurityFilterChain 을 따로 정의하지 않으면
* 이 기본 Security 구성이 적용된다.
*/
@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
@Bean
@ConditionalOnMissingBean(SecurityFilterChain.class)
public SecurityFilterChain kriSecurityFilterChain(
HttpSecurity http,
ObjectProvider<ApiKeyAuthFilter> apiKeyAuthFilterProvider,
JwtAuthenticationFilter jwtAuthenticationFilter
) throws Exception {
http
.httpBasic(AbstractHttpConfigurer::disable)
.csrf(AbstractHttpConfigurer::disable)
.cors(Customizer.withDefaults())
.sessionManagement(session ->
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
)
.authorizeHttpRequests(auth -> {
// ✅ yaml에서 정의한 public-paths 전부 permitAll
if (securityProperties.getPublicPaths() != null && !securityProperties.getPublicPaths().isEmpty()) {
auth.requestMatchers(securityProperties.getPublicPaths().toArray(String[]::new)).permitAll();
}
// ✅ 나머지는 전부 인증 필요
auth.anyRequest().authenticated();
});
// ✅ API Key 필터가 존재하면 먼저 태움
apiKeyAuthFilterProvider.ifAvailable(filter ->
http.addFilterBefore(filter, UsernamePasswordAuthenticationFilter.class)
);
// ✅ 그 다음 JWT 필터
http.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);
return http.build();
}
}

View File

@@ -0,0 +1,28 @@
package com.kri.common.security;
import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.List;
@Getter
@Setter
@ConfigurationProperties(prefix = "kri.security")
public class KriSecurityProperties {
/**
* 이 자동구성 사용 여부
*/
private boolean enabled = true;
/**
* 인증 없이 허용할 URL 패턴들
* 서비스에서 application.yml로 오버라이드
*/
private List<String> publicPaths = List.of(
"/v3/api-docs/**",
"/swagger-ui.html",
"/swagger-ui/**"
);
}

View File

@@ -0,0 +1,70 @@
package com.kri.common.swagger;
import com.kri.common.auth.apikey.ApiKeyProperties;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
@AutoConfiguration
@EnableConfigurationProperties(KriSwaggerProperties.class)
@ConditionalOnClass({OpenAPI.class, GroupedOpenApi.class})
@ConditionalOnProperty(prefix = "kri.swagger", name = "enabled", havingValue = "true", matchIfMissing = true)
@RequiredArgsConstructor
public class KriSwaggerAutoConfiguration {
private final KriSwaggerProperties properties;
private final ApiKeyProperties apiKeyProperties; // apikey.header-name 읽어오기 위해
@Bean
@ConditionalOnMissingBean
public OpenAPI kriOpenAPI() {
// 🔐 JWT Bearer + API-Key 스키마 정의
Components components = new Components()
.addSecuritySchemes("BearerAuth",
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT"))
.addSecuritySchemes("ApiKeyAuth",
new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name(apiKeyProperties.getHeaderName())); // 예: X-API-Key
// 🔐 기본적으로 두 보안 스키마를 전역에 적용
SecurityRequirement securityRequirement = new SecurityRequirement()
.addList("BearerAuth")
.addList("ApiKeyAuth");
return new OpenAPI()
.components(components)
.addSecurityItem(securityRequirement)
.info(new Info()
.title(properties.getTitle())
.description(properties.getDescription())
.version(properties.getVersion())
);
}
@Bean
@ConditionalOnMissingBean
public GroupedOpenApi kriGroupedOpenApi() {
GroupedOpenApi.Builder builder = GroupedOpenApi.builder()
.group("kri-api");
if (properties.getBasePackage() != null) {
builder.packagesToScan(properties.getBasePackage());
}
return builder.build();
}
}

View File

@@ -0,0 +1,22 @@
package com.kri.common.swagger;
import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
@Getter
@Setter
@ConfigurationProperties(prefix = "kri.swagger")
public class KriSwaggerProperties {
private boolean enabled = true;
private String title = "KRI API";
private String description = "KRI Common API Docs";
private String version = "v1";
/**
* 문서화할 base package (null 이면 전체)
*/
private String basePackage;
}

View File

@@ -0,0 +1,26 @@
package com.kri.common.webmvc;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.web.servlet.HandlerInterceptor;
@RequiredArgsConstructor
public class IpAccessControlInterceptor implements HandlerInterceptor {
private final IpAccessControlService ipAccessControlService;
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) throws Exception {
String clientIpAddress = IpUtil.getClientIp(request);
if (!ipAccessControlService.isAccessible(clientIpAddress)) {
response.sendError(HttpServletResponse.SC_FORBIDDEN);
return false;
}
return true;
}
}

View File

@@ -0,0 +1,20 @@
package com.kri.common.webmvc;
import lombok.RequiredArgsConstructor;
import org.springframework.security.web.util.matcher.IpAddressMatcher;
import java.util.List;
@RequiredArgsConstructor
public class IpAccessControlService {
private final KriIpAccessProperties properties;
public boolean isAccessible(String ipAddress) {
List<String> cidrs = properties.getEffectiveCidrs();
return cidrs.stream()
.map(IpAddressMatcher::new)
.anyMatch(matcher -> matcher.matches(ipAddress));
}
}

View File

@@ -0,0 +1,27 @@
package com.kri.common.webmvc;
import jakarta.servlet.http.HttpServletRequest;
public final class IpUtil {
private IpUtil() {
}
public static String getClientIp(HttpServletRequest request) {
// 1. Proxy 환경 고려: X-Forwarded-For 헤더 우선
String xff = request.getHeader("X-Forwarded-For");
if (xff != null && !xff.isBlank()) {
// X-Forwarded-For: client, proxy1, proxy2 ...
return xff.split(",")[0].trim();
}
// 2. 그 다음 X-Real-IP
String realIp = request.getHeader("X-Real-IP");
if (realIp != null && !realIp.isBlank()) {
return realIp;
}
// 3. 최후 fallback
return request.getRemoteAddr();
}
}

View File

@@ -0,0 +1,44 @@
package com.kri.common.webmvc;
import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
@Getter
@Setter
@ConfigurationProperties(prefix = "kri.webmvc.ip")
public class KriIpAccessProperties {
/**
* 공통에서 고정으로 들고 갈 기본 CIDR 들
* → setter 없음 (외부에서 못 바꿈)
*/
private final List<String> defaultCidrs = List.of(
"127.0.0.1/32", // 로컬 IPv4
"::1/128", // 로컬 IPv6
"10.10.13.0/24", //석오 내부망
"211.254.145.128/25" //석오 내부망 외부 IP
);
/**
* 서비스에서 추가로 넣고 싶은 CIDR 목록
* application.yml / properties 로 바인딩되는 리스트
*
* 예) kri.webmvc.ip.additional-cidrs[0]=10.10.0.0/16
*/
private List<String> additionalCidrs = new ArrayList<>();
/**
* 기본 + 추가를 합친 최종 목록
*/
public List<String> getEffectiveCidrs() {
return Stream.concat(defaultCidrs.stream(), additionalCidrs.stream())
.distinct()
.collect(Collectors.toList());
}
}

View File

@@ -0,0 +1,63 @@
package com.kri.common.webmvc;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@AutoConfiguration
@EnableConfigurationProperties(KriIpAccessProperties.class)
@ConditionalOnProperty(name = "common.webmvc.enabled", matchIfMissing = true)
@RequiredArgsConstructor
public class KriWebMvcAutoConfiguration {
private final KriIpAccessProperties ipProps; // 생성자 주입 (RequiredArgsConstructor)
@Bean
@ConditionalOnMissingBean
public IpAccessControlService ipAccessControlService(KriIpAccessProperties ipProps) {
return new IpAccessControlService(ipProps);
}
@Bean
@ConditionalOnMissingBean
public IpAccessControlInterceptor ipAccessControlInterceptor(IpAccessControlService service) {
return new IpAccessControlInterceptor(service);
}
// 선택 주입: 있으면 쓰고, 없으면 안 씀
private final ObjectProvider<IpAccessControlInterceptor> ipAccessControlInterceptorProvider;
/**
* 실제로 WebMvc 설정을 하는 WebMvcConfigurer Bean
*/
@Bean
public WebMvcConfigurer kriCommonWebMvcConfigurer() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
// 기본 CORS – 필요하면 나중에 조정
registry.addMapping("/**")
.allowedOriginPatterns("*")
.allowedMethods("*")
.allowedHeaders("*")
.allowCredentials(true);
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
ipAccessControlInterceptorProvider.ifAvailable(interceptor ->
registry.addInterceptor(interceptor)
.order(1)
.addPathPatterns("/swagger-ui/**", "/v3/api-docs/**")
);
}
};
}
}

View File

@@ -1,4 +1,7 @@
com.kri.common.auth.jwt.JwtAutoConfiguration
com.kri.common.security.KriSecurityAutoConfiguration
com.kri.common.web.CommonWebAutoConfiguration
com.kri.common.webmvc.KriWebMvcAutoConfiguration
com.kri.common.swagger.KriSwaggerAutoConfiguration
com.kri.common.redis.CommonRedisAutoConfiguration
com.kri.common.scheduling.CommonSchedulingAutoConfiguration
com.kri.common.auth.jwt.JwtAutoConfiguration