Spring Boot에서 OAuth2 의존성 추가로 로그인 화면이 나타나는 이유

최근 Spring Boot 프로젝트를 진행하면서 OAuth2 연동을 테스트하기 위해 관련 의존성만 추가했습니다.
그런데, 로그인 화면을 따로 만들지도 않았고, Spring Security 설정도 하지 않았는데, localhost:8080에 접속하자 기본 로그인 화면이 나타났습니다.

처음엔 당황했지만, Spring Boot 공식 문서와 의존성 구조를 살펴보며 원인을 파악했습니다. 이 글에서는 왜 이런 일이 발생했는지, 그리고 이를 해결하거나 활용하는 방법을 공유하려고 합니다.

---

왜 로그인 화면이 나타났을까?

프로젝트 설정

제가 추가한 의존성은 단 하나입니다:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

• Spring Security 관련 의존성을 직접 추가하지 않았습니다.
• Security 설정 클래스(WebSecurityConfigurerAdapter나 SecurityFilterChain)도 작성하지 않았습니다.
• 그럼에도 / 경로에 접속하면 Spring Security의 기본 로그인 화면이 출력됩니다.

---

원인: Spring Boot의 자동 구성(Auto-Configuration)

Spring Boot는 클래스패스에 특정 라이브러리가 존재하면 관련 기능을 자동으로 활성화하는 강력한 자동 구성 기능을 제공합니다. 이게 이번 현상의 핵심입니다.

1. OAuth2 Starter의 내부 구조

spring-boot-starter-oauth2-client는 내부적으로 Spring Security를 의존합니다.
Maven/Gradle의 의존성 트리를 살펴보면, 이 스타터는 spring-security-config, spring-security-web, spring-security-oauth2-client 같은 라이브러리를 자동으로 포함합니다.

# mvn dependency:tree 출력 예시
[INFO] +- org.springframework.boot:spring-boot-starter-oauth2-client:jar:3.0.5:compile
[INFO] |  +- org.springframework.security:spring-security-config:jar:6.0.3:compile
[INFO] |  +- org.springframework.security:spring-security-oauth2-client:jar:6.0.3:compile
[INFO] |  +- org.springframework.security:spring-security-web:jar:6.0.3:compile

즉, OAuth2 의존성을 추가하는 순간 Spring Security가 프로젝트에 포함됩니다.

2. Spring Security의 기본 동작

Spring Security가 클래스패스에 존재하면, Spring Boot는 **모든 HTTP 엔드포인트에 기본 인증(Basic Authentication)**을 적용합니다.
이는 Spring Boot의 Security Auto-Configuration에 의해 자동으로 설정됩니다.
공식 문서에서 이를 명확히 설명합니다:

“If Spring Security is on the classpath, Spring Boot automatically secures all HTTP endpoints with basic authentication.”
– Spring Boot Reference Guide, Security

• 결과적으로, / 경로에 접속하면 Spring Security가 보호된 페이지로 간주하고, 인증되지 않은 사용자를 기본 로그인 페이지로 리다이렉트합니다.
• 기본 로그인 페이지는 Spring Security가 제공하는 간단한 HTML 폼입니다.

---

해결 방법: 로그인 화면을 원치 않을 경우

만약 이 기본 로그인 화면을 원하지 않는다면, 다음 두 가지 방법 중 하나를 선택할 수 있습니다:

1. Security Auto-Configuration 비활성화

Spring Boot의 자동 보안 설정을 완전히 끄는 방법입니다.
application.properties 또는 application.yml에 다음 설정을 추가하세요:

spring.security.enabled=false

주의: 이 설정은 Spring Security 자체를 비활성화하므로, OAuth2 클라이언트 기능도 동작하지 않을 수 있습니다. OAuth2를 사용하려면 다음 방법이 더 적합합니다.

2. Spring Security 커스터마이징

Spring Security를 비활성화하지 않고, 원하는 대로 동작하도록 설정을 커스터마이징할 수 있습니다.
예를 들어, 특정 경로(예: /, /public)는 인증 없이 접근 가능하도록 설정할 수 있습니다:

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.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/public/**").permitAll() // 인증 없이 접근 허용
                .anyRequest().authenticated() // 나머지 요청은 인증 필요
            )
            .oauth2Login(); // OAuth2 로그인 활성화
        return http.build();
    }
}

• 위 코드는 /와 /public/** 경로는 누구나 접근 가능하도록 설정하고, 나머지 경로는 인증을 요구합니다.
• .oauth2Login()은 OAuth2 로그인을 활성화하여 Google, GitHub 같은 외부 제공자를 통해 로그인 가능.

---

부가 팁: 디버깅과 이해를 위한 도구

1. 의존성 트리 확인
   Maven이나 Gradle을 사용한다면, 의존성 트리를 확인해 어떤 라이브러리가 포함되었는지 파악하세요:또는 IntelliJ IDEA의 External Libraries 섹션에서 확인 가능.
2. mvn dependency:tree
3. Spring Security와 OAuth2의 관계
   OAuth2는 Spring Security 위에서 동작합니다. 따라서 spring-boot-starter-oauth2-client를 사용하면 Spring Security가 필수적으로 포함됩니다. 이를 이해하면 설정 과정이 훨씬 명확해집니다.
4. 로그로 디버깅
   Spring Security의 동작을 확인하려면 application.properties에 로깅 설정 추가:이렇게 하면 Security 필터 체인과 인증 흐름을 디버깅할 수 있습니다.
5. logging.level.org.springframework.security=DEBUG

---

결론

Spring Boot 프로젝트에서 spring-boot-starter-oauth2-client 의존성을 추가했을 때, 별도의 설정 없이도 로그인 화면이 나타나는 이유는 Spring Security의 자동 구성 때문입니다.

• spring-boot-starter-oauth2-client가 Spring Security를 포함.
• Spring Security가 클래스패스에 있으면, 모든 엔드포인트에 기본 인증을 적용.
• 결과적으로 / 경로 접속 시 기본 로그인 페이지가 표시됨.

이를 원치 않는다면 Security 설정을 비활성화하거나, 커스텀 Security 설정을 통해 원하는 경로만 인증하도록 조정할 수 있습니다.

이 글이 Spring Boot와 OAuth2를 처음 다루는 분들에게 도움이 되길 바랍니다!  궁금한 점이 있다면 댓글로 남겨주세요.