2026년 Spring Security로 API 보안

1. 왜 API 보안에 OAuth2.0이 필요한가?

2026년 현재, 우리의 디지털 생활은 API(Application Programming Interface)에 크게 의존하고 있습니다. 모바일 앱, 웹 서비스, 사물 인터넷(IoT) 기기 등 수많은 서비스가 API를 통해 데이터를 주고받으며 상호작용합니다. 이러한 API들은 사용자 정보, 금융 거래 기록, 개인 건강 데이터 등 민감한 정보를 다루는 경우가 많기 때문에, 강력한 보안은 선택이 아닌 필수입니다.

만약 API 보안이 제대로 이루어지지 않는다면 어떤 문제가 발생할까요? 가장 심각한 문제는 데이터 유출입니다. 해커가 취약한 API를 통해 데이터베이스에 접근하면 수많은 사용자 정보가 유출될 수 있습니다. 또한, 무단 접근을 통해 사용자의 동의 없이 계정을 조작하거나, 서비스에 불법적인 행위를 가할 수도 있습니다. 이는 기업의 신뢰도 하락은 물론, 법적 문제로까지 이어질 수 있습니다.

전통적인 API 보안 방식으로는 사용자 ID와 비밀번호를 직접 주고받는 방법이 있었지만, 이는 보안상 매우 취약합니다. 클라이언트(예: 모바일 앱)가 사용자의 비밀번호를 직접 저장하거나 전송하는 과정에서 탈취될 위험이 크기 때문입니다. 이러한 문제를 해결하기 위해 등장한 것이 바로 OAuth2.0입니다.

OAuth2.0의 등장 배경과 역할

OAuth2.0은 “권한 위임(Delegated Authorization)”을 위한 개방형 표준 프로토콜입니다. 사용자의 비밀번호를 직접 공유하지 않고, 특정 서비스(클라이언트)가 다른 서비스(리소스 서버)에 접근할 수 있는 제한된 권한을 부여하는 메커니즘을 제공합니다. 예를 들어, 여러분이 어떤 쇼핑 앱에 가입할 때 “카카오 계정으로 로그인”을 선택한다고 가정해봅시다. 이때 쇼핑 앱은 여러분의 카카오 비밀번호를 직접 알 필요 없이, 카카오로부터 여러분의 이름이나 프로필 사진 같은 특정 정보에 접근할 수 있는 권한만 얻게 됩니다. 이것이 바로 OAuth2.0의 핵심 원리입니다.

2012년에 발표된 OAuth2.0은 기존 OAuth1.0의 복잡성을 개선하고 모바일 환경에 더 적합하도록 설계되었습니다. 이후 수많은 웹 서비스와 모바일 앱에 적용되며 사실상의 표준으로 자리 잡았습니다. 특히 2026년 현재, 마이크로서비스 아키텍처와 분산 시스템이 보편화되면서, 서비스 간 안전한 통신과 사용자 인증/권한 부여를 위해 OAuth2.0의 중요성은 더욱 커지고 있습니다.

2. OAuth2.0의 핵심 구성 요소 및 권한 부여 타입

OAuth2.0을 이해하려면 먼저 그 구성 요소들과 권한 부여 타입(Grant Type)을 파악하는 것이 중요합니다. 이들은 OAuth2.0 흐름의 핵심을 이룹니다.

OAuth2.0의 4가지 역할

OAuth2.0은 다음 네 가지 주요 역할이 상호작용하며 동작합니다.

주요 권한 부여 타입 (Authorization Grant Types)

OAuth2.0은 클라이언트의 특성과 보안 요구사항에 따라 여러 가지 권한 부여 타입을 제공합니다. 이 중에서 가장 널리 사용되고 권장되는 방식은 인가 코드 부여 (Authorization Code Grant) 방식입니다.

1. 인가 코드 부여 (Authorization Code Grant)

이 방식은 클라이언트가 사용자 에이전트(웹 브라우저)를 통해 인가 코드를 받고, 이 인가 코드를 사용하여 직접 인증 서버에 접근 토큰을 요청하는 방식입니다. 클라이언트 비밀(Client Secret)이 노출될 위험이 적고, 중간자 공격에 강해 가장 보안성이 뛰어납니다. 특히 모바일 앱이나 웹 애플리케이션에 적합하며, PKCE (Proof Key for Code Exchange) 확장과 함께 사용하면 보안을 더욱 강화할 수 있습니다.

2. 클라이언트 자격 증명 부여 (Client Credentials Grant)

이 방식은 리소스 소유자(사용자)의 개입 없이 클라이언트 자체의 자격 증명(Client ID, Client Secret)만을 사용하여 접근 토큰을 얻는 방식입니다. 주로 서버 간 통신이나 백엔드 서비스가 자체적으로 API에 접근해야 할 때 사용됩니다. 사용자 컨텍스트가 필요 없는 시스템 간의 통신에 적합합니다.

3. 갱신 토큰 (Refresh Token)

접근 토큰(Access Token)은 보안상의 이유로 수명이 짧게 설정됩니다 (예: 5분~1시간). 접근 토큰이 만료되면 클라이언트는 다시 전체 인가 코드 흐름을 거쳐야 하는데, 이는 사용자 경험에 좋지 않습니다. 이때 갱신 토큰(Refresh Token)이 사용됩니다. 갱신 토큰은 접근 토큰보다 긴 수명(예: 1일~수개월)을 가지며, 만료된 접근 토큰 대신 새로운 접근 토큰을 발급받을 때 사용됩니다. 갱신 토큰은 매우 민감하므로, 안전하게 보관하고 한 번만 사용할 수 있도록 하는 등의 추가 보안 조치가 필요합니다.

3. Spring Security를 활용한 인증 서버 구축

Spring Boot 환경에서 OAuth2.0 인증 서버를 구축하는 것은 spring-security-oauth2-authorization-server 라이브러리 덕분에 훨씬 쉬워졌습니다. 이 라이브러리는 2020년 5월에 Spring Security 5.x 버전부터 공식적으로 제공되기 시작했으며, 기존의 spring-security-oauth2 프로젝트의 후속작이라고 볼 수 있습니다. 2026년 현재는 Spring Boot 3.x 및 Spring Security 6.x 이상에서 이 라이브러리를 사용하는 것이 표준입니다.

필요한 의존성 추가

먼저 pom.xml (Maven) 또는 build.gradle (Gradle)에 다음 의존성을 추가합니다.

<!-- Maven (pom.xml) -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.security</groupId>
        <artifactId>spring-security-oauth2-authorization-server</artifactId>
        <version>1.2.3</version<!-- 최신 안정 버전으로 대체 -->
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- 기타 필요한 의존성 (JDBC, Lombok 등) -->
</dependencies>

인증 서버 설정 (AuthorizationServerConfig)

인증 서버의 핵심은 @Configuration 클래스에서 OAuth2AuthorizationServerConfiguration을 확장하거나 커스터마이징하는 것입니다. 여기서는 클라이언트 등록, 토큰 설정, JWK(JSON Web Key) 설정 등을 정의합니다.

@Configuration
@EnableWebSecurity
public class AuthorizationServerConfig {

    @Bean
    @Order(1) // 우선순위 높게 설정
    public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
        OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);
        http.getConfigurer(OAuth2AuthorizationServerConfigurer.class)
            .oidc(Customizer.withDefaults()); // OpenID Connect 활성화 (필요시)
        http
            .exceptionHandling(exceptions ->
                exceptions.authenticationEntryPoint(
                    new LoginUrlAuthenticationEntryPoint("/login") // 로그인 페이지 지정
                )
            )
            .oauth2ResourceServer(resourceServer -> // 리소스 서버로써의 역할도 수행 가능 (토큰 검증)
                resourceServer.jwt(Customizer.withDefaults()));
        return http.build();
    }

    @Bean
    @Order(2) // 일반 웹 보안 필터 체인
    public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize ->
                authorize
                    .requestMatchers("/login", "/oauth2/**", "/error").permitAll() // 로그인 및 OAuth2 엔드포인트 허용
                    .anyRequest().authenticated()
            )
            .formLogin(Customizer.withDefaults()); // 기본 로그인 폼 사용
        return http.build();
    }

    @Bean
    public UserDetailsService userDetailsService() {
        // 실제 운영에서는 JDBC 또는 LDAP 기반의 UserDetailsService 구현
        UserDetails userDetails = User.withDefaultPasswordEncoder()
            .username("user")
            .password("password")
            .roles("USER")
            .build();
        return new InMemoryUserDetailsManager(userDetails);
    }

    @Bean
    public RegisteredClientRepository registeredClientRepository() {
        // 인메모리 클라이언트 등록 (운영에서는 JDBC 등으로 관리)
        RegisteredClient registeredClient = RegisteredClient.withId(UUID.randomUUID().toString())
            .clientId("public-client")
            .clientSecret("{noop}secret") // {noop}은 비밀번호 인코딩 안 함을 의미 (개발용)
            .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
            .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
            .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
            .redirectUri("http://127.0.0.1:8080/login/oauth2/code/public-client") // 클라이언트 리다이렉트 URI
            .redirectUri("http://127.0.0.1:8080/authorized") // 추가 리다이렉트 URI
            .scope(OidcScopes.OPENID) // OpenID Connect 스코프
            .scope(OidcScopes.PROFILE)
            .scope("api.read") // 커스텀 스코프
            .clientSettings(ClientSettings.builder().requireAuthorizationConsent(true).build()) // 동의 화면 필요
            .tokenSettings(TokenSettings.builder()
                .accessTokenTimeToLive(Duration.ofMinutes(5)) // 접근 토큰 5분 유효
                .refreshTokenTimeToLive(Duration.ofDays(1)) // 갱신 토큰 1일 유효
                .reuseRefreshTokens(false) // 갱신 토큰 재사용 금지 (보안 강화)
                .build())
            .build();

        RegisteredClient anotherClient = RegisteredClient.withId(UUID.randomUUID().toString())
            .clientId("internal-service")
            .clientSecret("{noop}internal-secret")
            .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
            .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS) // 클라이언트 자격 증명 부여 타입
            .scope("internal.api")
            .tokenSettings(TokenSettings.builder()
                .accessTokenTimeToLive(Duration.ofMinutes(30))
                .build())
            .build();

        return new InMemoryRegisteredClientRepository(registeredClient, anotherClient);
    }

    @Bean
    public JWKSource<SecurityContext> jwkSource() {
        RSAKey rsaKey = generateRsa();
        JWKSet jwkSet = new JWKSet(rsaKey);
        return new ImmutableJWKSet<>(jwkSet);
    }

    private static RSAKey generateRsa() {
        KeyPair keyPair = generateRsaKey();
        RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
        RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
        return new RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(UUID.randomUUID().toString())
            .build();
    }

    private static KeyPair generateRsaKey() {
        try {
            KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
            keyPairGenerator.initialize(2048);
            return keyPairGenerator.generateKeyPair();
        } catch (Exception ex) {
            throw new IllegalStateException(ex);
        }
    }

    @Bean
    public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
        return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource);
    }

    @Bean
    public AuthorizationServerSettings authorizationServerSettings() {
        return AuthorizationServerSettings.builder()
            .issuer("http://localhost:9000") // 인증 서버의 발급자 URI
            .build();
    }

    @Bean
    public OAuth2TokenCustomizer<JwtEncodingContext> jwtTokenCustomizer() {
        return context -> {
            if (OAuth2TokenType.ACCESS_TOKEN.equals(context.getTokenType())) {
                context.getClaims().claims(claims ->
                    claims.put("custom_claim", "권퓨터의 OAuth2.0 가이드"));
            }
        };
    }
}

JWT (JSON Web Token) 서명 키 설정

인증 서버는 접근 토큰을 JWT 형태로 발급합니다. 이 JWT는 변조되지 않았음을 보장하기 위해 개인 키로 서명됩니다. jwkSource() 메서드는 이 서명에 사용될 JWK(JSON Web Key)를 제공합니다. 리소스 서버는 이 인증 서버의 공개 키를 사용하여 JWT의 유효성을 검증하게 됩니다. 실제 운영 환경에서는 키를 안전하게 관리하고 주기적으로 갱신하는 전략이 필요합니다.

4. Spring Security를 활용한 리소스 서버 구축

리소스 서버는 클라이언트가 전달한 접근 토큰의 유효성을 검증하고, 토큰에 포함된 권한(scope)에 따라 보호된 리소스를 제공하는 역할을 합니다. Spring Security는 OAuth2.0 리소스 서버를 쉽게 구축할 수 있도록 spring-security-oauth2-resource-server 모듈을 제공합니다.

필요한 의존성 추가

리소스 서버 프로젝트에도 다음 의존성을 추가합니다.

<!-- Maven (pom.xml) -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.security</groupId>
        <artifactId>spring-security-oauth2-resource-server</artifactId>
    </dependency>
    <!-- 기타 필요한 의존성 -->
</dependencies>

리소스 서버 설정 (ResourceServerConfig)

리소스 서버는 JWT 토큰을 검증하기 위해 인증 서버의 공개 키를 알아야 합니다. 이는 주로 인증 서버가 제공하는 JWK Set URI를 통해 이루어집니다. application.yml 또는 application.properties에 해당 URI를 설정합니다.

// application.yml (리소스 서버)
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:9000 # 인증 서버의 issuer URI
          jwk-set-uri: http://localhost:9000/oauth2/jwks # 인증 서버의 JWK Set URI

// ResourceServerConfig.java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity // @PreAuthorize 활성화를 위해 추가
public class ResourceServerConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize ->
                authorize
                    .requestMatchers("/public/**").permitAll() // 공개 API
                    .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin.read") // 특정 스코프 필요
                    .requestMatchers("/api/**").authenticated() // 모든 /api 경로는 인증 필요
                    .anyRequest().permitAll()
            )
            .oauth2ResourceServer(oauth2ResourceServer ->
                oauth2ResourceServer.jwt(Customizer.withDefaults()) // JWT 기반 리소스 서버 설정
            )
            .csrf(AbstractHttpConfigurer::disable); // CSRF 비활성화 (API 서버의 경우)
        return http.build();
    }
}

컨트롤러에서 권한 부여 (@PreAuthorize)

리소스 서버의 컨트롤러에서는 @PreAuthorize 어노테이션을 사용하여 메소드 레벨에서 접근 권한을 제어할 수 있습니다. 이는 특정 스코프(Scope)를 가진 토큰만 해당 API에 접근할 수 있도록 강제합니다.

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

    @GetMapping("/users")
    @PreAuthorize("hasAuthority('SCOPE_api.read')") // 'api.read' 스코프가 필요
    public String getUsers(JwtAuthenticationToken jwt) {
        // JWT로부터 사용자 정보 및 클레임 접근 가능
        return "보호된 사용자 목록입니다. (User: " + jwt.getName() + ", Scopes: " + jwt.getAuthorities() + ")";
    }

    @PostMapping("/products")
    @PreAuthorize("hasAuthority('SCOPE_api.write')") // 'api.write' 스코프가 필요
    public String createProduct() {
        return "새로운 제품이 생성되었습니다.";
    }

    @GetMapping("/admin/dashboard")
    @PreAuthorize("hasAuthority('SCOPE_admin.read')") // 'admin.read' 스코프가 필요
    public String getAdminDashboard() {
        return "관리자 대시보드 정보입니다.";
    }

    @GetMapping("/public/info")
    public String getPublicInfo() {
        return "누구나 접근 가능한 공개 정보입니다.";
    }
}

5. 실전 적용: OAuth2.0 연동 및 보안 고려사항

인증 서버와 리소스 서버를 구축했다면, 이제 클라이언트(프론트엔드)와 어떻게 연동하고 실제 운영 환경에서 어떤 보안 고려사항이 있는지 살펴보겠습니다.

클라이언트(프론트엔드)에서의 OAuth2.0 연동

웹 브라우저 기반의 클라이언트(SPA, Server-Side Rendered App)나 모바일 앱에서는 주로 인가 코드 부여 방식과 PKCE(Proof Key for Code Exchange) 확장을 함께 사용합니다. PKCE는 인가 코드가 중간에 탈취되더라도 공격자가 이를 이용해 접근 토큰을 발급받지 못하도록 방지하는 역할을 합니다.

보안 취약점 방지

OAuth2.0은 강력한 보안 메커니즘을 제공하지만, 잘못 구현하면 여전히 취약점이 발생할 수 있습니다. 다음 사항들을 항상 고려해야 합니다.

API Gateway와의 통합

마이크로서비스 아키텍처에서는 일반적으로 API Gateway를 사용하여 모든 외부 요청을 중앙에서 처리합니다. 이때 API Gateway에서 OAuth2.0 토큰 검증을 수행하면 각 리소스 서버는 비즈니스 로직에만 집중할 수 있어 효율적입니다. Spring Cloud Gateway와 Spring Security를 함께 사용하면 쉽게 통합할 수 있습니다.

자주 묻는 질문 (FAQ)

Q. OAuth2.0과 OpenID Connect(OIDC)는 무엇이 다른가요?

A. OAuth2.0은 접근 권한을 위임하는 “권한 부여” 프로토콜인 반면, OpenID Connect는 OAuth2.0 위에 구축된 “인증” 프로토콜입니다. OIDC는 사용자 신원 정보를 포함하는 ID 토큰(ID Token)을 제공하여 사용자가 누구인지 확인할 수 있게 해줍니다.

Q. spring-security-oauth2와 spring-security-oauth2-authorization-server의 차이점은 무엇인가요?

A. spring-security-oauth2는 Spring Security 5.x 이전 버전에서 OAuth2.0 기능을 제공하던 레거시 프로젝트입니다. spring-security-oauth2-authorization-server는 Spring Security 5.x부터 공식적으로 제공되는 새로운 모듈로, 최신 OAuth2.0 및 OIDC 사양을 완벽하게 지원하며 더 안정적이고 유연합니다.

Q. Refresh Token은 어디에 저장해야 안전한가요?

A. Refresh Token은 Access Token보다 수명이 길고 민감하므로, 클라이언트 측에서는 HTTP Only 속성이 설정된 보안 쿠키나 암호화된 로컬 저장소(모바일의 경우 키체인/키스토어)에 저장하는 것이 가장 안전합니다. 절대 JavaScript에서 직접 접근할 수 없도록 해야 합니다.

Q. OAuth2.0 환경에서 사용자 역할(Role)은 어떻게 관리하나요?

A. 사용자 역할은 보통 JWT의 클레임(Claim)에 포함시켜 전달합니다. 예를 들어, roles 클레임에 ["ADMIN", "USER"]와 같이 정의하고, 리소스 서버에서 이를 파싱하여 @PreAuthorize("hasRole('ADMIN')")와 같이 권한을 부여할 수 있습니다.

7. 마무리: 안전한 API의 미래

지금까지 Spring Security와 OAuth2.0을 활용하여 안전한 백엔드 API를 구축하는 방법에 대해 인증 서버와 리소스 서버 관점에서 자세히 살펴보았습니다. OAuth2.0은 복잡해 보일 수 있지만, 그 핵심 원리를 이해하고 Spring Security의 강력한 기능을 활용하면 누구나 견고하고 확장 가능한 보안 시스템을 만들 수 있습니다.

2026년 이후에도 API 보안의 중요성은 더욱 커질 것입니다. 새로운 위협과 기술 발전 속에서 OAuth2.0은 계속해서 진화하며 중요한 역할을 수행할 것입니다. 이 가이드가 여러분의 백엔드 보안 역량을 강화하고, 더 안전한 서비스를 개발하는 데 큰 도움이 되기를 바랍니다.