[TS] Spring Security + Spring OAuth2 Client 적용 과정 중 발생한 문제 트러블 슈팅

🤔 오류 발생

새로운 토이 프로젝트, NEO를 개발하면서 소셜 로그인 기능 구현을 위해 OAuth2 Client 개발을 진행했습니다.

개발이 끝난 후, API 요청을 통해 해당 기능을 검토하는 도중 데이터베이스 상에 OAuth2 인증 과정을 진행한 이후 새로운 회원 가입 데이터가 저장되지 않는 이상한 현상을 발견했습니다.

데이터베이스의 문제라면, 분명 로그가 작성되었을텐데, 해당 로그가 없는 것도 이상해 문제의 원인을 트래킹했습니다.

OAuth2 인증 과정 중, 사용자의 정보를 얻어와 데이터베이스에 저장하는 코드는, OAuth2UserService<OAuth2UserRequest, OAuth2User>를 implement한 NEOOAuth2UserService에 있습니다.

@Slf4j
@Service
@RequiredArgsConstructor
public class NEOOAuth2UserService implements OAuth2UserService<OAuth2UserRequest, OAuth2User> {

    private final NEOUserRepository userRepository;

    @Override
    public OAuth2User loadUser(OAuth2UserRequest userRequest) throws OAuth2AuthenticationException {
        log.info("CustomOAuth2UserService.loadUser() 실행 - OAuth2 로그인 요청 진입");

        OAuth2UserService<OAuth2UserRequest, OAuth2User> delegate = new DefaultOAuth2UserService();
        OAuth2User oAuth2User = delegate.loadUser(userRequest);

        String registrationId = userRequest.getClientRegistration().getRegistrationId();
        NEOOAuth2ProviderType providerType = NEOOAuth2ProviderType.ofRegistrationId(registrationId);
        String userNameAttributeName = userRequest.getClientRegistration()
                .getProviderDetails().getUserInfoEndpoint().getUserNameAttributeName(); // OAuth2 로그인 시 키(PK)가 되는 값
        Map<String, Object> attributes = oAuth2User.getAttributes(); // 소셜 로그인에서 API가 제공하는 userInfo의 Json 값(유저 정보들)

        NEOOAuth2AttributesDTO extractAttributes = NEOOAuth2AttributesDTO.of(providerType, userNameAttributeName, attributes);

        NEOUserEntity createdUser = getUser(extractAttributes, providerType); // getUser() 메소드로 User 객체 생성 후 반환

        return new NEOCustomOAuth2User(
                Collections.singleton(new SimpleGrantedAuthority(createdUser.getUserType().getKey())),
                attributes,
                extractAttributes.getNameAttributeKey(),
                createdUser.getEmail(),
                createdUser.getUserType(),
                createdUser.getUserName(),
                createdUser.getPhoneNumber(),
                createdUser.getGender()
        );
    }

    private NEOUserEntity getUser(NEOOAuth2AttributesDTO attributes, NEOOAuth2ProviderType providerType) {
        NEOUserEntity foundUser;

        try {
            foundUser = userRepository.findByProviderTypeAndSocialID(providerType,
                            attributes.getOauth2UserInfo().getId())
                    .orElseGet(() -> saveUser(attributes, providerType));
        } catch (Exception e){
            throw new NEOUnexpectedException("OAuth 진행 과정 중, DB 에러가 발생했습니다. 서버 관린자에게 문의하세요.");
        }

        return foundUser;
    }

    private NEOUserEntity saveUser(NEOOAuth2AttributesDTO attributes, NEOOAuth2ProviderType socialType) {
        NEOUserEntity createdUser = attributes.toEntity(socialType, attributes.getOauth2UserInfo());
        return userRepository.save(createdUser);
    }

}

해당 클래스의 loadUser()에서, getUser()와 saveUser()를 호출하는 것을 확인할 수 있습니다.

DB에 저장되지 않았다는 것은, getUser() 메소드가 호출되지 않았다는 것이고, 마찬가지로 loadUser() 메소드가 호출되지 않았음을 뜻합니다. 디버거 포인트를 통해서도 확인한 사실입니다.

☕️ Security Config Code

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class NEOSecurityConfig {

    private final NEOOAuth2SuccessHandler oAuth2LoginSuccessHandler;
    private final NEOOAuth2FailureHandler oAuth2LoginFailureHandler;
    private final NEOOAuth2UserService customOAuth2UserService;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // 폼 로그인 사용 X
        http.formLogin(AbstractHttpConfigurer::disable)
                // httpBasic 인증 방식 사용 X
                .httpBasic(AbstractHttpConfigurer::disable)
                // 브라우저를 사용하지 않는다는 전제 하에 csrf X (NEO는 앱)
                .csrf(AbstractHttpConfigurer::disable)
                // 세션 미사용, JWT Token 방식 사용
                .sessionManagement((sessionManagement) -> sessionManagement.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // OAuth2 소셜 로그인
                .oauth2Login((oauth2Login) -> oauth2Login
                        .successHandler(oAuth2LoginSuccessHandler)
                        .failureHandler(oAuth2LoginFailureHandler)
                        .userInfoEndpoint(userInfoEndpointConfig -> userInfoEndpointConfig.userService(customOAuth2UserService)))
                // URL별 권한 관리
                .authorizeHttpRequests(requests -> requests
                        // 로그인 관련 URL 모두 허가
                        .requestMatchers("/login", "/oauth2/authorization/**", "/api/v1/oauth2/**").permitAll()
                        // API 개발 문서 URL 모두 허가
                        .requestMatchers("/docs/**").permitAll()
                        // 나머지 URL
                        .anyRequest().authenticated());

        return http.build();
    }

}

☕️ application-oauth.yml

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: {google-client-id}
            client-secret: {google-client-secret}
            redirect-uri: http://localhost:8080/api/v1/oauth2/google
            scope: profile, email

          naver:
            client-id: {naver-client-id}
            client-secret: {naver-client-secret}
            redirect-uri: http://localhost:8080/api/v1/oauth2/naver
            authorization-grant-type: authorization_code
            scope: name, email, gender, mobile
            client-name: Naver

          kakao:
            client-id: {kakao-client-id}
            client-secret: {kakao-client-secret}
            redirect-uri: http://localhost:8080/api/v1/oauth2/kakao
            client-authentication-method: POST
            authorization-grant-type: authorization_code
            scope: account_email, gender
            client-name: Kakao

        provider:
          naver:
            authorization_uri: https://nid.naver.com/oauth2.0/authorize
            token_uri: https://nid.naver.com/oauth2.0/token
            user-info-uri: https://openapi.naver.com/v1/nid/me
            user_name_attribute: response

          kakao:
            authorization-uri: https://kauth.kakao.com/oauth/authorize
            token-uri: https://kauth.kakao.com/oauth/token
            user-info-uri: https://kapi.kakao.com/v2/user/me
            user-name-attribute: id

위의 코드와 같이 NEOSecurityConfig의 oauth2Login.userInfoEndpoint()에 우리가 개발한 OAuth2UserService를 등록했는데 왜 loadUser()를 호출하지 않았던 것일까요?

해당 문제를 해결하는 과정에서 OAuth2 Client에 대해 깊게 파고들어 더 잘 이해하는 과정이 되었기에 해당 내용을 정리하기로 마음먹었습니다.

🤔 1. OAuth2UserService는 잘 등록되었는가?

oauth2Login.userInfoEndpoint 메소드는 OAuth2의 Authorization Server의 사용자 정보 엔드포인트를 규정하는 메소드입니다.

따라서 UserInfoEndpointConfig.userSerivce()를 통해서 Resource Owner의 사용자 정보를 얻어올 수 있는 사용자 정보 엔드포인트를 설정하게 됩니다.

파라미터로 OAuth2UserService를 요구하고 있는데, 해당 타입은 우리가 코드에서 구현한 NEOOAuth2UserService에 해당합니다.

OAuth2UserService를 잠시 살펴보면, Resource Owner의 사용자 정보를 획득할 수 있는 책임이 있는 인터페이스로써,

Authorization Server로부터 얻어온 Access Token을 통해 OAuth2User의 형식을 가진 AuthenticatedPrincipal을 얻어올 수 있습니다. 즉 Resource Server로부터 Access Token을 통해 Resource Owner의 정보를 가져올 수 있다는 의미입니다.

우선, OAuth2UserService가 잘 등록되었는지 확인하기 위해서는 OAuth2LoginConfigurer의 init 메소드를 살펴볼 수 있었습니다.

OAuth2LoginConfigurer의 init() 메소드는 다음과 같은 일을 합니다.

@Override
    public void init(B http) throws Exception {
        OAuth2LoginAuthenticationFilter authenticationFilter = new OAuth2LoginAuthenticationFilter(
                OAuth2ClientConfigurerUtils.getClientRegistrationRepository(this.getBuilder()),
                OAuth2ClientConfigurerUtils.getAuthorizedClientRepository(this.getBuilder()), this.loginProcessingUrl);
        authenticationFilter.setSecurityContextHolderStrategy(getSecurityContextHolderStrategy());
        this.setAuthenticationFilter(authenticationFilter);
        super.loginProcessingUrl(this.loginProcessingUrl);
        if (this.loginPage != null) {
            // Set custom login page
            super.loginPage(this.loginPage);
            super.init(http);
        }
        else {
            Map<String, String> loginUrlToClientName = this.getLoginLinks();
            if (loginUrlToClientName.size() == 1) {
                // Setup auto-redirect to provider login page
                // when only 1 client is configured
                this.updateAuthenticationDefaults();
                this.updateAccessDefaults(http);
                String providerLoginPage = loginUrlToClientName.keySet().iterator().next();
                this.registerAuthenticationEntryPoint(http, this.getLoginEntryPoint(http, providerLoginPage));
            }
            else {
                super.init(http);
            }
        }
        OAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest> accessTokenResponseClient = this.tokenEndpointConfig.accessTokenResponseClient;
        if (accessTokenResponseClient == null) {
            accessTokenResponseClient = new DefaultAuthorizationCodeTokenResponseClient();
        }
        OAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService = getOAuth2UserService();
        OAuth2LoginAuthenticationProvider oauth2LoginAuthenticationProvider = new OAuth2LoginAuthenticationProvider(
                accessTokenResponseClient, oauth2UserService);
        GrantedAuthoritiesMapper userAuthoritiesMapper = this.getGrantedAuthoritiesMapper();
        if (userAuthoritiesMapper != null) {
            oauth2LoginAuthenticationProvider.setAuthoritiesMapper(userAuthoritiesMapper);
        }
        http.authenticationProvider(this.postProcess(oauth2LoginAuthenticationProvider));
        boolean oidcAuthenticationProviderEnabled = ClassUtils
                .isPresent("org.springframework.security.oauth2.jwt.JwtDecoder", this.getClass().getClassLoader());
        if (oidcAuthenticationProviderEnabled) {
            OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService = getOidcUserService();
            OidcAuthorizationCodeAuthenticationProvider oidcAuthorizationCodeAuthenticationProvider = new OidcAuthorizationCodeAuthenticationProvider(
                    accessTokenResponseClient, oidcUserService);
            JwtDecoderFactory<ClientRegistration> jwtDecoderFactory = this.getJwtDecoderFactoryBean();
            if (jwtDecoderFactory != null) {
                oidcAuthorizationCodeAuthenticationProvider.setJwtDecoderFactory(jwtDecoderFactory);
            }
            if (userAuthoritiesMapper != null) {
                oidcAuthorizationCodeAuthenticationProvider.setAuthoritiesMapper(userAuthoritiesMapper);
            }
            http.authenticationProvider(this.postProcess(oidcAuthorizationCodeAuthenticationProvider));
        }
        else {
            http.authenticationProvider(new OidcAuthenticationRequestChecker());
        }
        this.initDefaultLoginFilter(http);
    }

- OAuth2LoginAuthenticationFilter를 생성하고 설정합니다.
- loginPage를 설정하며, 설정된 값이 없다면 기본 설정으로 loginPage를 생성합니다.
- provider에 맞는 링크를 구성합니다. 예를 들어, [kakao, naver, google]을 사용한다면 각각의 authorization을 가능케 하는 링크를 생성합니다.
- Authorization grant code를 Access Token으로 교환하는 엔드포인트를 설정합니다.(OAuth2AccessTokenResponseClient를 OAuth2LoginAuthenticationProvider에 등록)
- AccessToken을 통해 Resource 서버에 Resource Owner의 정보를 획득할 수 있는 OAuth2UserService를 설정합니다.
- 기본 로그인 페이지 생성 및 각 Provider의 로그인 폼으로 접속하는 URL 생성 등.

init 메소드 내의 getOAuth2UserService() 메소드를 통해, 우리가 만든 NEOOAuth2UserService 객체가 잘 들어간 것을 확인할 수 있었습니다.

객체가 잘 등록되었음에도, loadUser()가 호출되지 않아 더욱 궁금해졌습니다.

🤔 2. 문제 추적하기

그래서 곧바로 loadUser()는 누가 호출하는지, 트래킹 해보도록 하겠습니다.

loadUser() 메소드를 사용하는 곳은 총 6개이지만 OpenID를 다루는 Oidc나, OAuth2UserService를 간단하게 위임할 수 있는 DelegatingOAuth2UserService, 우리가 구현한 NEOOAuth2UserService를 제외하면

OAuth2LoginAuthenticationProvider가 실질적으로 loadUser()를 호출하고 있습니다.

해당 부분을 따라가면, OAuth2LoginAuthenticationProvider의 authenticate 메소드에 도착하게 됩니다.

그리고 해당 authenticate 메소드는 ProviderManager의 authenticate에서 호출하고 있습니다.

해당 메소드는 전달받은 Authentication 객체로 하여금 인증을 시도하는 메소드로, AuthenticationProvider에 의해 시도됩니다.

즉, 정상적으로 OAuth2LoginAuthenticationProvider가 잘 등록되었다면, ProviderManager의 authenticate 메소드에서, getProviders()를 통해 for문을 돌며 해당 프로바이더에 대해 authenticate 메소드를 호출하면서 인증 과정을 처리하게 됩니다.

그러나, 정상적으로 등록이 되지 않았기 때문에 해당 메소드는 호출되지 않았던 것입니다.

정상적으로 등록되지 않은 원인을 좀 더 파악하기 위해서 해당 authenticate 메소드를 누가 호출했는지 살펴보려고 합니다.

한 번 더 타고 올라가면, OAuth2LoginAuthenticationFilter에 도착하게 됩니다.

☕️ OAuth2LoginAuthenticationFilter

An implementation of an AbstractAuthenticationProcessingFilter for OAuth 2.0 Login. This authentication Filter handles the processing of an OAuth 2.0 Authorization Response for the authorization code grant flow and delegates an OAuth2LoginAuthenticationToken to the AuthenticationManager to log in the End-User. The OAuth 2.0 Authorization Response is processed as follows: Assuming the End-User (Resource Owner) has granted access to the Client, the Authorization Server will append the code and state parameters to the redirect_uri (provided in the Authorization Request) and redirect the End-User's user-agent back to this Filter (the Client). This Filter will then create an OAuth2LoginAuthenticationToken with the code received and delegate it to the AuthenticationManager to authenticate. Upon a successful authentication, an OAuth2AuthenticationToken is created (representing the End-User Principal) and associated to the Authorized Client using the OAuth2AuthorizedClientRepository. Finally, the OAuth2AuthenticationToken is returned and ultimately stored in the SecurityContextRepository to complete the authentication processing.
[인용 : Javadoc]

☕️ OAuth2LoginAuthenticationFilter 한글 요약
- AbstractAuthenticationProcessingFilter의 OAuth2.0 로그인을 위한 구현체
- OAuth2의 "Authorization code grant" 방식에서 OAuth 2.0 Authorization Response을 다루고, "OAuth2LoginAuthenticationToken"을 AuthenticationManager에게 위임해서 최종 사용자를 로그인 할 수 있도록 도와주는 필터.

- OAuth 2.0 Authorization Response의 프로세스
1. Resource Owner가 Client로 접근할 수 있다는 가정 하에, 인증 서버는 redirect_uri에 code와 state를 추가
2. 최종 사용자의 에이전트를 다시 이 필터로 리다이렉션
3. OAuth2LoginAuthenticationToken을 생성
4. AuthenticationManager에게 인증 위임
5. 성공적으로 인증이 완료 되면, OAuth2LoginAuthenticationToken의 필드를 바탕으로 OAuth2AuthenticationToken이 생성.

OAuth2LoginAuthenticationFilter에서 중점적으로 보아야 할 것은 총 두 가지 입니다.

1. OAuth2LoginAuthenticationFilter는 OAuth2LoginConfigurer의 init 메소드에서 생성자를 통해 생성된 적이 있다.
2. attemptAuthentication 메소드

첫 번째 중점으로 OAuth2LoginAuthenticationFilter는 OAuth2LoginConfigurer의 init 메소드에서 생성자를 통해 생성된 적이 있습니다.

가장 처음 나오게 되는 코드죠.

OAuth2LoginAuthenticationFilter authenticationFilter = new OAuth2LoginAuthenticationFilter(
                OAuth2ClientConfigurerUtils.getClientRegistrationRepository(this.getBuilder()),
                OAuth2ClientConfigurerUtils.getAuthorizedClientRepository(this.getBuilder()), this.loginProcessingUrl);

생성자를 살펴보면, 아래와 같은 생성자를 사용하고 있었습니다.

OAuth2LoginConfigurer.loginProcessUrl이 OAuth2LoginAuthenticationFilter을 생성할 때 전달되고, 그 값은 그대로 부모에게 filterProcessesUrl으로 전달되게 됩니다.

OAuth2LoginAuthenticationFilter의 부모는, AbstractAuthenticationProcessingFilter입니다.

위와 같은 코드로 인해 AbstractAuthenticationProcessingFilter의 requiresAuthenticationRequestMatcher는 OAuth2LoginConfigurer.loginProcessUrl의 영향을 고스란히 받고 있었습니다.

이 점을 기억한 상태에서, 아래의 글을 보면 실마리가 풀리게 됩니다.

두 번째 중점으로 OAuth2LoginAuthenticationFilter의 attemptAuthentication 메소드는, Resource Owner가 소셜 로그인 진행하고 난 이후에 동작하며 Authorization Server로부터 전달된 code를 HttpServletRequest로부터 가져오도록 합니다.

그리고 이 메소드는, AbstractAuthenticationProcessingFilter의 doFilter 메소드에서 실행되고 있었습니다.

여기서 잘 보아야 할 부분은, try문을 들어가기 전의 조건입니다.

requiresAuthentication의 boolean 리턴값에 의해 아래의 attemptAuthentication을 실행할 것인지, 아닌지가 결정됩니다.

해당 메소드로 가서 어떤 로직인지 확인해보도록 하겠습니다.

해당 메소드는 이 필터가 로그인 요청 실행을 시도해야 하는지를 결정하는 역할을 하는 메소드입니다.

즉, this.requiresAuthenticationRequestMatcher.matches()의 값이 false라면, 해당 필터가 로그인 프로세스 실행을 시도하지 않는다는 것입니다.

this.requiresAuthenticationRequestMatcher는 위에서 보았듯이, OAuth2LoginConfigurer.loginProcessUrl의 영향을 받습니다.

loginProcessUrl은 OAuth2LoginAuthenticationFilter의 DEFAULT\_FILTER\_PROCESSES\_URI이며, 해당 값은 "/login/oauth2/code/*"로 고정되어 있습니다.

다시 위의 application-oauth.yml을 살펴보면,

http://localhost:8080/api/v1/oauth2/*

와 같이 설정되어 있기 때문에, 해당 url로는 로그인 프로세스를 실행하지 않았던 것입니다.

"어? 단순히 application.yml에 redirect-url을 내가 원하는 방향으로 변경한다고 해서 바로 동작하는게 아니구나?"

그렇다면 위의 내용을 토대로 문제를 해결할 수 있는 방법은, OAuth2LoginConfigurer의 loginProcessUrl을 변경하는 것입니다.

해당 메소드를 사용하면 모든 문제를 해결할 수 있습니다.

따라서 의외로 간단히 Security Config 코드에서 단 한 줄만 추가 하면 해결할 수 있는 문제였네요.

☕️ 변경된 Security Config Code

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class NEOSecurityConfig {

    private final NEOOAuth2SuccessHandler oAuth2LoginSuccessHandler;
    private final NEOOAuth2FailureHandler oAuth2LoginFailureHandler;
    private final NEOOAuth2UserService customOAuth2UserService;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // 폼 로그인 사용 X
        http.formLogin(AbstractHttpConfigurer::disable)
                // httpBasic 인증 방식 사용 X
                .httpBasic(AbstractHttpConfigurer::disable)
                // 브라우저를 사용하지 않는다는 전제 하에 csrf X (NEO는 앱)
                .csrf(AbstractHttpConfigurer::disable)
                // 세션 미사용, JWT Token 방식 사용
                .sessionManagement((sessionManagement) -> sessionManagement.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // OAuth2 소셜 로그인
                .oauth2Login((oauth2Login) -> oauth2Login
                        .loginProcessingUrl("/api/v1/oauth2/*") // 추가됨!
                        .successHandler(oAuth2LoginSuccessHandler)
                        .failureHandler(oAuth2LoginFailureHandler)
                        .userInfoEndpoint(userInfoEndpointConfig -> userInfoEndpointConfig.userService(customOAuth2UserService)))
                // URL별 권한 관리
                .authorizeHttpRequests(requests -> requests
                        // 로그인 관련 URL 모두 허가
                        .requestMatchers("/login", "/oauth2/authorization/**", "/api/v1/oauth2/**").permitAll()
                        // API 개발 문서 URL 모두 허가
                        .requestMatchers("/docs/**").permitAll()
                        // 나머지 URL
                        .anyRequest().authenticated());

        return http.build();
    }

}

🤔 3. 총정리 및 후기

문제는 loginProcessUrl을 설정하지 않았기 때문에 발생했습니다.

단순히 application.yml에 redirect-url을 설정하면 내부적으로 oauth2 client가 모든 것을 처리해 줄 것이라는 안일한 생각이 해당 문제를 발생시켰네요.

그래도 이러한 실수 덕분에 oauth2 client가 어떻게 authroization code grant 방식을 처리하는지, 내부를 들여다 볼 수 있는 좋은 기회가 된 것 같습니다.

앞으로는 단순한 직관보다는 좀 더 깊은 이해를 한 상태로 개발하는 습관을 들여야겠다는 생각이 들었습니다.

저작자표시 비영리 동일조건

'⚙️ Trouble Shooting' 카테고리의 다른 글

[Trouble Shooting] Lombok 사용시, 어노테이션이 적용되지 않는 간단한 문제 해결 (0)	2023.08.14
[Trouble Shooting] Swagger-ui를 접속했을 때 404 error가 나는 경우 (0)	2023.08.14
[TS] JPA error - Specified key was too long; max key length is 1000 bytes (0)	2023.03.23
[TS] 새로운 프로젝트 생성 및 Spring WebFlux 적용 과정 중 생긴 트러블 슈팅 (0)	2023.03.12