[프로젝트] OAuth2 인증 구현하기 (KakaoOAuth) + SecurityConfig 설정

✅ Git

https://github.com/ellaCoo/sns/pull/46

📌 상황

이전에 SpringSecurity로 로그인 기능(https://github.com/ellaCoo/sns/pull/27)을 구현했는데,
회원가입 기능말고 카카오 로그인 기능을 추가하려고 한다.

 

1. build.gradle 에 Spring Security OAuth2 Client 의존성 추가한다

implementation 'org.springframework.boot:spring-boot-starter-oauth2-client' // kakao auth                

 

2. application.yaml 파일에 카카오 OAuth2 스프링 프로퍼티 설정을 추가한다

카카오 개발자 문서를 참고하여 OAuth 2.0 서비스를 사용하는데 필요한 정보를 정리함
여기서 client-id, client-secret은 비밀정보이므로 실제 값을 넣지 않고, 나중에 외부 환경변수로 넣을 수 있도록 함

  security:
    oauth2:
      client:
        registration:
          kakao:
            client-id: ${KAKAO_OAUTH_CLIENT_ID}
            client-secret: ${KAKAO_OAUTH_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/kakao"
            client-authentication-method: POST
        provider:
          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

 

3. https://developers.kakao.com/

- 로그인 후 애플리케이션 새로 생성

- 앱 설정 > 플랫폼 > Web (현재 로컬에서 진행하고 있으므로 http://localhost:8080 만 추가)

- 제품 설정 > 카카오 로그인 > Redirect URI

- 제품 설정 > 동의항목 > 닉네임 설정

- 제품 설정 > 보안 > Client Secret 코드 발급

     ⇒ application.yaml 의 client-secret: ${KAKAO_OAUTH_CLIENT_SECRET}

- 앱 설정 > 앱 키 > REST API 키

     ⇒ application.yaml 의 client-id: ${KAKAO_OAUTH_CLIENT_ID}

앱 설정 > 플랫폼 > Web

제품 설정 > 카카오 로그인 > Redirect URI

 

4. 인증 정보를 다루는 SnsPrincipal 에 OAuth 인증 정보를 다룰 수 있도록 기능 추가

OAuth2User 인터페이스를 구현해서 Spring OAuth Client 도 기존과 동일하게 인증 정보를 인식할 수 있게끔 함

public record SnsPrincipal(
        String username,
        String password,
        Collection<? extends GrantedAuthority> authorities,
        String email,
        String nickname,
        String memo,
        Map<String, Object> oAuth2Attributes
) implements UserDetails, OAuth2User {

  **@Override
    public Map<String, Object> getAttributes() {
        return oAuth2Attributes;
    }

    @Override
    public String getName() {
        return username;
    }**

 

5. 카카오 OAuth2 인증 후 반환된 사용자 정보를 처리 - KakaoOAuth2Response

record KakaoOAuth2Response
- record : 불변성(immutable)을 보장, 모든 필드를 자동으로 생성자에 넣어줌
- 카카오에서 반환된 OAuth2 응답 데이터를 담는 DTO
- id (카카오 사용자 ID), connectedAt(카카오 서비스에 연결된 시점), properties(기타 속성), kakaoAccount(카카오 계정 정보)

record KakaoAccount
- KakaoOAuth2Response 내부에 정의된 클래스
- 카카오 계정 정보에 대한 세부 정보 + 이메일과 프로필 정보에 대한 필드 처리

public static KakaoOAuth2Response from(Map<String, Object> attributes)
- 카카오 OAuth2 응답으로부터 KakaoOAuth2Response 객체를 생성하는 정적 팩토리 메서드
- JSON이나 Map 형식으로 받은 데이터를 파싱해 각 필드에 맞게 매핑

public String email()
- 카카오 계정 정보에서 이메일을 반환

public String nickname()
- 카카오 계정 정보에서 닉네임을 반환

public record KakaoOAuth2Response(
        Long id,
        LocalDateTime connectedAt,
        Map<String, Object> properties,
        KakaoAccount kakaoAccount
) {
    public record KakaoAccount(
            Boolean profileNicknameNeedsAgreement,
            Profile profile,
            Boolean hasEmail,
            Boolean emailNeedsAgreement,
            Boolean isEmailValid,
            Boolean isEmailVerified,
            String email
    ) {
        public record Profile(String nickname) {
            public static Profile from(Map<String, Object> attributes) {
                return new Profile(String.valueOf(attributes.get("nickname")));
            }
        }

        public static KakaoAccount from(Map<String, Object> attributes) {
            return new KakaoAccount(
                    Boolean.valueOf(String.valueOf(attributes.get("profile_nickname_needs_agreement"))),
                    Profile.from((Map<String, Object>) attributes.get("profile")),
                    Boolean.valueOf(String.valueOf(attributes.get("has_email"))),
                    Boolean.valueOf(String.valueOf(attributes.get("email_needs_agreement"))),
                    Boolean.valueOf(String.valueOf(attributes.get("is_email_valid"))),
                    Boolean.valueOf(String.valueOf(attributes.get("is_email_verified"))),
                    String.valueOf(attributes.get("email"))
            );
        }

        public String nickname() { return this.profile().nickname(); }
    }

    public static KakaoOAuth2Response from(Map<String, Object> attributes) {
        return new KakaoOAuth2Response(
                Long.valueOf(String.valueOf(attributes.get("id"))),
                LocalDateTime.parse(
                        String.valueOf(attributes.get("connected_at")),
                        DateTimeFormatter.ISO_INSTANT.withZone(ZoneId.systemDefault())
                ),
                (Map<String, Object>) attributes.get("properties"),
                KakaoAccount.from((Map<String, Object>) attributes.get("kakao_account"))
        );
    }

    public String email() { return this.kakaoAccount().email(); }
    public String nickname() { return this.kakaoAccount().nickname(); }
}

 

6. SecurityConfig 클래스 설정 - Spring Security와 카카오 OAuth2 인증을 사용하여 사용자 인증 및 권한 부여를 처리

Spring Security 는 인증,인가에 대한 처리를 여러개의 필터를 통해 연쇄적으로 실행한다.
Security Filter Chain 빈을 생성하는 securityFilterChain 메소드가 Security Filter Chain 에 대한 전반적인 설정을 구성하며
해당 메소드에 매개변수인 HttpSecurity 가 설정을 기반으로 Security Filter Chain 을 생성한다.

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(
            HttpSecurity http,
            OAuth2UserService<OAuth2UserRequest, OAuth2User> oAuth2UserService
    ) throws Exception {
        return http
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers(PathRequest.toStaticResources().atCommonLocations()).permitAll()
                        .requestMatchers("/api/**").permitAll()
                        .requestMatchers(
                                HttpMethod.GET,
                                "/",
                                "/posts",
                                "/posts/hashtag"
                        ).permitAll()
                        .requestMatchers(
                                HttpMethod.POST,
                                "/posts"
                        ).permitAll()
                        .anyRequest().authenticated()
                )
                .formLogin(withDefaults())
                .logout(logout -> logout.logoutSuccessUrl("/"))
                .oauth2Login(oAuth -> oAuth
                        .userInfoEndpoint(userInfo -> userInfo
                                .userService(oAuth2UserService)
                        )
                )
                .csrf(csrf -> csrf.ignoringRequestMatchers("/api/**"))
                .build();
    }

    @Bean
    public UserDetailsService userDetailsService(UserAccountService userAccountService) {
        return username -> userAccountService
                .searchUser(username)
                .map(SnsPrincipal::fromDto)
                .orElseThrow(() -> new UsernameNotFoundException("유저를 찾을 수 없습니다 - username: " + username));
    }

    @Bean
    public OAuth2UserService<OAuth2UserRequest, OAuth2User> oAuth2UserService(
            UserAccountService userAccountService,
            PasswordEncoder passwordEncoder
    ) {
        final DefaultOAuth2UserService delegate = new DefaultOAuth2UserService();

        return userRequest -> {
            OAuth2User oAuth2User = delegate.loadUser(userRequest);

            KakaoOAuth2Response kakaoResponse = KakaoOAuth2Response.from(oAuth2User.getAttributes());
            String registrationId = userRequest.getClientRegistration().getRegistrationId();
            String providerId = String.valueOf(kakaoResponse.id());
            String username = registrationId + "_" + providerId;
            String dummyPassword = passwordEncoder.encode("{bcrypt}" + UUID.randomUUID());

            return userAccountService.searchUser(username)
                    .map(SnsPrincipal::fromDto)
                    .orElseGet(() ->
                            SnsPrincipal.fromDto(
                                    userAccountService.saveUser(
                                            username,
                                            dummyPassword,
                                            kakaoResponse.email(),
                                            kakaoResponse.nickname(),
                                            null
                                    )
                            )
                    );
        };
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return PasswordEncoderFactories.createDelegatingPasswordEncoder();
    }
}

 

6-1. securityFilterChain 메서드

HTTP 요청에 대한 보안 필터 체인을 설정
- 모든 요청이 Spring Security의 필터를 거치기 때문에, 애플리케이션에 들어오는 모든 요청에 대해 보안 설정을 적용

Spring Security의 보안 구성을 담당하며, 여러 필터를 설정하여 애플리케이션의 인증과 인가를 제어함

authorizeHttpRequests
: HTTP 요청에 대해 어떤 요청을 허용하고 어떤 요청을 인증해야 하는지 정의

- PathRequest.toStaticResources().atCommonLocations().permitAll()
    : 정적 리소스(CSS, JS 등)에 대한 접근은 모두 허용
- GET /, /posts, /posts/hashtag: 이 GET 요청들 모두 허용
- POST /posts: POST 요청도 인증 없이 허용
- anyRequest().authenticated(): 그 외 모든 요청은 인증 필요

formLogin(withDefaults())
: 기본적으로 제공되는 로그인 폼을 사용하겠다는 설정

logout(logout -> logout.logoutSuccessUrl("/"))
: 로그아웃 후에 루트 페이지("/")로 리다이렉트

oauth2Login
: OAuth2를 사용하여 로그인할 수 있도록 설정합니다. userService(oAuth2UserService)를 통해 사용자 정보를 처리하는 OAuth2UserService를 지정

csrf(csrf -> csrf.ignoringRequestMatchers("/api/**"))
: CSRF 보호는 /api/** 경로에서는 비활성화

 

6-2. userDetailsService 메서드

사용자 정보를 가져오는 로직을 정의
- 폼 로그인을 통해 사용자가 로그인을 시도할 때 호출됨

UserDetailsService는 Spring Security에서 인증 정보를 조회할 때 사용됨

username을 받아서 UserAccountService를 통해 사용자를 조회한다

 

6-3. oAuth2UserService 메서드

OAuth2 사용자 정보를 처리하는 서비스 객체를 생성
(여기에선 카카오 OAuth2 로그인을 처리하는 방식 정의)

사용자가 카카오 통해 인증 완료
→ 카카오 서버가 애플리케이션에 사용자 정보를 전달하면 이 때 OAuth2UserRequest 객체가 생성되고, oAuth2UserService 메서드가 호출됨

이 메서드가 반환한 OAuth2User 객체가 Spring Security의 인증 정보로 사용됨

DefaultOAuth2UserService delegate = new DefaultOAuth2UserService();
: 기본 OAuth2 사용자 정보를 로드하는 서비스를 위임받는다

OAuth2User oAuth2User = delegate.loadUser(userRequest);
: OAuth2 요청을 통해 카카오로부터 사용자 정보를 가져온다

KakaoOAuth2Response.from(oAuth2User.getAttributes())
: 카카오 응답에서 필요한 사용자 정보를 가져온다
- 여기서 ID, 이메일, 닉네임 등의 정보가 추출됨

registrationId, providerId, username
: 카카오 사용자 ID를 기반으로 username을 생성
- registrationId는 "kakao"이고, providerId는 카카오의 사용자 ID
- 두개 결합하여 고유한 username 생성

dummyPassword
: 암호화된 임시 비밀번호를 생성
- 실제로는 카카오 로그인을 통해서만 접근할 수 있기 때문에 비밀번호는 중요한 요소가 아니지만, 시스템적으로는 필요하므로 더미값을 사용
- 사용자가 이미 존재하는 경우, SnsPrincipal::fromDto로 변환하여 반환
- 사용자가 존재하지 않는 경우, 새로운 사용자 계정을 생성하여 저장한 뒤 반환

 

✅ 카카오 OAuth2 인증 흐름 다이어그램

[1] 사용자 요청 (카카오 로그인 버튼 클릭)
     |
     v
[2] 클라이언트 → 카카오 서버 (OAuth2 Authorization 요청)
     URL: <https://kauth.kakao.com/oauth/authorize>
     - 클라이언트 ID, redirect URI, 응답 유형(authorization_code) 등 전달
     |
     v
[3] 사용자 → 카카오 서버 (사용자 동의 화면)
     - 사용자가 카카오 동의 화면에서 정보 제공에 동의
     |
     v
[4] 카카오 서버 → 클라이언트 (Authorization Code 전달)
     - 클라이언트는 Authorization Code를 받음
     - redirect URI로 리다이렉트됨
     |
     v
[5] 클라이언트 → 카카오 서버 (Access Token 요청)
     URL: <https://kauth.kakao.com/oauth/token>
     - Authorization Code와 함께 클라이언트 ID, 비밀키(client secret), redirect URI 등 전달
     |
     v
[6] 카카오 서버 → 클라이언트 (Access Token 응답)
     - Access Token을 포함한 인증 정보를 반환
     |
     v
[7] 클라이언트 → 카카오 API 서버 (사용자 정보 요청)
     URL: <https://kapi.kakao.com/v2/user/me>
     - Access Token을 헤더에 포함하여 사용자 정보 요청
     |
     v
[8] 카카오 서버 → 클라이언트 (사용자 정보 반환)
     - 사용자 ID, 이메일, 닉네임 등 반환
     |
     v
[9] Spring Security - `OAuth2UserService` 실행
     - `oAuth2UserService` 메서드에서 사용자 정보 처리
     |
     v
[10] 사용자 계정 처리 (DB 조회 및 저장)
     - 사용자가 존재하면 로그인 처리, 없으면 새로 생성
     |
     v
[11] 인증 완료 후 리다이렉트
     - 사용자가 애플리케이션에 로그인된 상태로 리다이렉트됨

 

✅ 정리

SecurityConfig 클래스에서 각 메서드가 실제로는 Spring의 빈으로 등록됨

→ 각 과정에서 메서드가 직접 호출되는 것이 아니라 Spring이 내부적으로 처리함

 

빈으로 등록된다?

Spring의 빈으로 등록된다는 것
= 해당 메서드가 애플리케이션이 시작될 때 Spring 컨텍스트에 의해 자동으로 생성되고 관리된다
⇒ 한 번 생성된 후 Spring Security가 인증 및 인가 과정에서 필요한 로직을 빈으로 등록된 객체를 통해 자동으로 처리함

예시:
securityFilterChain 메서드→ 이후 모든 요청이 들어올 때마다 이 빈이 Security 필터 체인으로 동작함→ 애플리케이션 시작 시점에 한 번 호출되고 SecurityFilterChain 빈을 생성

빈으로 동작하는 원리

1. 애플리케이션이 시작되면 
Spring은 @Configuration 어노테이션이 붙은 클래스를 스캔해서
해당 클래스 안의 @Bean 어노테이션이 붙은 메서드들을 실행
⇒ Spring의 빈으로 등록돼서 관리됨

2. 사용자 요청이 들어오면 Spring Security는 내부적으로 securityFilterChain에서 설정된 필터 체인을 통해 요청을 처리함

- OAuth2 로그인이 필요한 경우 → OAuth2UserService 호출
- UserDetailsService가 필요한 경우 → Spring Security가 자동으로 이를 참조해 사용자 정보를 조회

결론

1. 사용자가 카카오 로그인을 시도할 때
- Spring Security는 자동으로 OAuth2 인증 과정을 관리
- 사용자가 인증을 완료하면 → Spring Security는 자동으로 OAuth2UserService 빈을 호출해서 사용자 정보를 처리
- 이때 oAuth2UserService 빈이 호출됨 → 사용자가 DB에 있는지 확인하고, 새로운 사용자를 생성하는 로직 실행

2. 폼 로그인을 시도할 때
- 사용자가 username과 password를 입력
→ Spring Security는 UserDetailsService 빈을 사용해서
해당 username을 가진 사용자를 찾음
(이 과정에서 userDetailsService 메서드가 호출되는 게 아니라, 이미 등록된 빈을 통해 처리됨)