[Spring Security] OAuth2 로그인부터 JWT 인증까지: 전체 흐름 정리

현대적인 백엔드 아키텍처에서 가장 복잡하면서도 중요한 지점은 단연 인증(Authentication)과 인가(Authorization)다.
소셜 로그인(OAuth2)의 간편함과 서버의 확장성(JWT)을 동시에 잡으려다 보면, 필터와 핸들러가 얽혀 전체 흐름을 놓치기 쉽다.
오늘은 이 복잡한 퍼즐 조각들을 하나로 합쳐, 요청 1건이 우리 시스템을 어떻게 관통하는지 그 생명 주기를 완벽히 정리해 본다.

1. 전체 흐름 다이어그램 (Sequence Diagram)

전체 흐름을 이해하는 가장 좋은 방법은 사용자의 요청이 각 컴포넌트를 거쳐가는 순서를 보는 것이다.

 

2. 역할 분담: 누가 무엇을 책임지는가?

이 아키텍처에서 각 컴포넌트는 명확한 단일 책임을 가진다.

1. OAuth2 (Social Login): 로그인 진입점 역할을 하며, 소셜 서비스로부터 사용자를 식별(Identification)할 정보를 가져오는 책임을 진다.
2. JWT (Stateless Token): 로그인 이후 API 호출 시마다 매번 소셜 서버를 거치지 않도록, 인증 상태를 증명하는 '신분증' 역할을 한다.
3. JwtAuthenticationFilter (Gatekeeper): 매 API 요청의 최전선에서 신분증(JWT)이 위조되지는 않았는지 검증하고, 서버 내부에 인증 객체를 세팅한다.
4. SecurityContext (Vault): 인증된 사용자의 정보를 요청이 끝날 때까지 안전하게 보관하는 임시 보관소다.

 

 

3. 심층 분석: 코드 포인트로 따라가는 4단계 흐름

실제 코드를 읽을 때 어떤 순서로 파악해야 하는지 짚어본다.

📌 STEP 1. SecurityConfig (전략 수립)

모든 보안의 시작점이다. 어떤 URL을 대중에게 공개하고, 어떤 URL을 토큰 검증 없이 통과시킬지 결정한다.

• 체크 포인트: http.authorizeHttpRequests 설정과 oauth2Login 설정이 어떻게 연결되어 있는지 확인해야 한다.

 

📌 STEP 2. CustomOAuth2UserService (사용자 식별)

소셜 서버에서 가져온 사용자 정보를 우리 시스템의 DB와 대조하는 지점이다.

• 핵심 로직: 신규 사용자인지 기존 사용자인지 판별하여 회원가입 혹은 정보를 업데이트하는 비즈니스 로직이 위치한다.

 

📌 STEP 3. OAuth2JwtSuccessHandler (토큰 발행)

소셜 인증이 완전히 성공하면 실행되는 핸들러다. 여기가 바로 "Session 시대에서 JWT 시대로 넘어가는 브릿지"다.

• 핵심 로직: JwtTokenProvider를 호출하여 Access/Refresh Token을 생성하고, 클라이언트(프론트엔드)가 이 토큰을 받을 수 있도록 URL 파라미터나 쿠키에 실어 리다이렉트한다.

 

📌 STEP 4. JwtAuthenticationFilter (매 요청 인증)

사용자가 API를 호출할 때마다 실행되는 필터다.

• 핵심 로직: Authorization: Bearer <Token> 헤더를 읽어 토큰을 파싱한다. 유효하다면 SecurityContextHolder에 Authentication 객체를 주입한다. 이 작업이 성공해야만 뒤에 있는 컨트롤러가 @CurrentUser와 같은 어노테이션으로 사용자 정보를 바로 꺼내 쓸 수 있다.

 

 

4. 실무 팁: 흐름을 놓치지 않는 법

• 로그 확인: 인증이 안 될 때는 JwtAuthenticationFilter에 디버그 로그를 찍어 토큰이 헤더에 제대로 실려오는지, 혹은 만료된 것은 아닌지 가장 먼저 확인하자.
• 책임의 분리: 컨트롤러에서 사용자 정보를 조회하는 로직을 직접 짜지 마라. 이미 필터에서 SecurityContext에 정보를 넣어두었으므로, 스프링 시큐리티의 기능을 활용해 주입받는 것이 객체 지향적이다.

 

5. 마무리하며

인증/인가의 흐름은 마치 공항의 입국 심사와 같다. OAuth2는 여권을 발급받는 과정이고, JWT는 비행기를 타기 위해 들고 있는 탑승권이다. 그리고 Security Filter는 게이트에서 탑승권을 검사하는 보안 요원이다. 이 비유를 머릿속에 넣고 코드를 보면, 수많은 클래스 사이에서도 길을 잃지 않을 것이다.