[Vite/React + Spring Boot] 카카오 소셜 로그인 완벽 연동 가이드

Spring & SpringBoot

[Vite/React + Spring Boot] 카카오 소셜 로그인 완벽 연동 가이드

창따오 2025. 12. 11. 18:43

728x90

📝 1단계: 카카오 개발자 센터 및 환경 설정

1. 카카오 개발자 센터 설정 요약

REST API 키: 발급 후 확인. (Client ID로 사용)
로그인 Redirect URI: http://localhost:3000/oauth/kakao 등록.
로그아웃 Redirect URI (SSO 해제용): http://localhost:3000 등록.
동의 항목: 닉네임, 이메일 등 필수 항목 설정.

2. 환경 변수 (.env) 설정

# .env (프로젝트 루트)
VITE_KAKAO_REST_API_KEY="YOUR_REST_API_KEY"
VITE_KAKAO_REDIRECT_URI="http://localhost:3000/oauth/kakao"

💻 2단계: 프론트엔드 (React + Zustand) 구현 상세

1. LoginPage.jsx (카카오 인증 시작)

환경 변수를 사용하여 카카오 인증 서버로 리다이렉트하는 URL을 구성합니다.

// src/pages/login/LoginPage.jsx
// ...
const KAKAO_REST_API_KEY = import.meta.env.VITE_KAKAO_REST_API_KEY; 
const KAKAO_LOGOUT_REDIRECT_URI = "http://localhost:3000"; 

const handleKakaoLogin = () => {
    // 💡 SSO 세션을 끊기 위해 먼저 카카오 로그아웃 페이지로 이동
    const kakaoLogoutUrl = 
        `https://kauth.kakao.com/oauth/logout?client_id=${KAKAO_REST_API_KEY}&logout_redirect_uri=${KAKAO_LOGOUT_REDIRECT_URI}`;
    
    window.location.href = kakaoLogoutUrl; 
};

2. KakaoRedirectHandler.jsx (인증 코드 처리 및 이중 호출 방지)

가장 중요하게 invalid_grant 오류를 방지하기 위한 isProcessed 플래그를 사용합니다.

// src/pages/login/KakaoRedirectHandler.jsx
// ...
function KakaoRedirectHandler() {
    const { setAuthInfo } = useAuthStore();
    const [isProcessed, setIsProcessed] = useState(false); // ⭐️ 이중 호출 방지
    
    useEffect(() => {
        const code = new URLSearchParams(location.search).get("code");

        if (!code) { /* ... 실패 처리 ... */ return; }
        if (isProcessed) { return; } // ⭐️ 이미 처리했으면 종료

        setIsProcessed(true); // 플래그 설정
        
        const handleKakaoCode = async (authCode) => {
            try {
                const res = await kakaoLogin(authCode); // 백엔드 API 호출
                if (res.success && res.data) {
                    setAuthInfo(res.data);
                    navigate("/home");
                } else {
                    // 백엔드에서 비즈니스 오류 발생 시 처리
                    customError(res.msg || "로그인 처리 오류");
                    navigate("/");
                }
            } catch (error) {
                // HTTP 통신 오류 발생 시 처리 (400, 500 등)
                console.error("API 최종 실패:", error.response || error);
                customError("서버 통신 오류가 발생했습니다.");
                navigate("/");
            } finally {
                setLoading(false);
            }
        };

        handleKakaoCode(code);
    }, [location, navigate]); 
    // ... (리턴 UI)
}

3. API 클라이언트 (authApi.js)

백엔드로 인증 코드를 전송하는 함수를 정의합니다.

JavaScript

// src/api/authApi.js
import axiosInstance from "../api/axiosInstance";

export const kakaoLogin = async (code) => {
    try {
        // 백엔드는 { "code": "..." } JSON 객체를 기대합니다.
        const response = await axiosInstance.post("/auth/kakao/login", { code });
        return response.data; 
    } catch (error) {
        console.error("❌ 카카오 로그인 요청 실패:", error);
        throw error;
    }
};

4. 상태 관리 (useAuthStore.js) - SSO 로그아웃

logout 시 서비스 상태 초기화 후 브라우저를 카카오 로그아웃 URL로 리다이렉트합니다.

JavaScript

// src/store/useAuthStore.js
// ... (KAKAO_REST_API_KEY, KAKAO_LOGOUT_REDIRECT_URI 상수 정의)

logout: () => {
    // 1. 서비스 상태 초기화 (Zustand, localStorage)
    // ...

    // 2. ⭐️ 카카오 SSO 세션 로그아웃을 위해 브라우저 리다이렉트 ⭐️
    if (KAKAO_REST_API_KEY && KAKAO_LOGOUT_REDIRECT_URI) {
        const kakaoLogoutUrl = 
            `https://kauth.kakao.com/oauth/logout?client_id=${KAKAO_REST_API_KEY}&logout_redirect_uri=${KAKAO_LOGOUT_REDIRECT_URI}`;
        window.location.href = kakaoLogoutUrl;
    } else {
        window.location.href = "/";
    }
},

🌐 4단계: 백엔드 (Spring Boot) 구현 상세

1. UserService.java (핵심 로직)

getKakaoToken 헬퍼 메서드에 에러 상세 로그를 추가하여 디버깅을 용이하게 합니다.

Java

// UserService.java (getKakaoToken 헬퍼 메서드)

private KakaoTokenResponse getKakaoToken(String authCode) {
    // ... (Headers 및 Params 설정)

    try {
        ResponseEntity<KakaoTokenResponse> response = restTemplate.exchange(
                kakaoTokenUri, HttpMethod.POST, request, KakaoTokenResponse.class
        );
        // ... (성공 처리)

    } catch (HttpClientErrorException e) { // ⭐️ 4xx 에러 상세 로그
        // 401 Unauthorized, 400 Invalid Grant 등의 오류 상세 정보를 로그에 기록
        log.error("카카오 토큰 발급 실패 (HTTP Error {}): {}", e.getStatusCode(), e.getResponseBodyAsString());
        throw new AccountInfoException("카카오 서버 통신 오류");
    } catch (Exception e) {
        log.error("카카오 Access Token 요청 중 예외 발생: {}", e.getMessage());
        throw new AccountInfoException("카카오 서버 통신 오류");
    }
}

// kakaoLogin 메서드 (회원가입/로그인 처리)
@Transactional
public UserResponse kakaoLogin(String authCode) {
    // 1. 토큰 받기 (getKakaoToken)
    // 2. 사용자 정보 받기 (getKakaoUserInfo)
    // 3. 카카오 ID로 DB 조회 (자동 회원가입 또는 로그인)
    // 4. JWT 발급 및 UserResponse 반환
}

2. UserController.java (에러 핸들링)

인증 코드 누락 시 사용자 정의 예외를 사용하여 깔끔하게 처리합니다.

Java

// UserController.java
@PostMapping("/auth/kakao/login")
public SingleResult<UserResponse> kakaoLogin(@RequestBody Map<String, String> request) {
    String code = request.get("code");
    
    // 💡 인증 코드 누락 시 사용자 정의 예외 throw
    if (code == null || code.isEmpty()) {
        throw new KakaoCodeNullException("카카오 인증 코드가 누락되었습니다.");
    }
    
    return responseService.handleSingleResult(userService.kakaoLogin(code));
}

🌐 4단계: 백엔드 (Spring Boot) 구현 상세

백엔드에서는 프론트엔드에서 전달받은 인증 코드(code)를 사용하여 카카오 서버와 통신하고, 최종적으로 자체 서비스의 JWT 토큰을 발급하는 역할을 합니다.

1. UserController.java (API 엔드포인트)

/auth/kakao/login 엔드포인트는 프론트엔드로부터 code를 JSON 형태로 받아 UserService로 전달하는 게이트웨이 역할을 합니다.

Java

// src/main/java/.../controller/UserController.java

@RestController
@RequiredArgsConstructor
@Slf4j
public class UserController {
    // ... (의존성 주입)

    /** ✅ 카카오 로그인 */
    @PostMapping("/auth/kakao/login")
    public SingleResult<UserResponse> kakaoLogin(@RequestBody Map<String, String> request) {
        String code = request.get("code");
        
        // 💡 인증 코드 누락 검증: 사용자 정의 예외 처리
        if (code == null || code.isEmpty()) {
            throw new KakaoCodeNullException("카카오 인증 코드가 누락되었습니다.");
        }
        
        // Service Layer로 코드 전달 및 로그인 처리 위임
        return responseService.handleSingleResult(userService.kakaoLogin(code));
    }
    
    // ... (기존 API 메서드)
}

2. UserService.java (핵심 비즈니스 로직)

UserService는 카카오 API 통신을 담당하는 헬퍼 메서드를 통해 Access Token과 사용자 정보를 획득하고, 이 정보를 바탕으로 DB 연동(회원가입/로그인)을 처리합니다.

A. kakaoLogin (회원 연동 및 JWT 발급)

카카오의 고유 ID를 서비스의 userId로 사용하여 회원가입/로그인 여부를 결정합니다.

// src/main/java/.../service/UserService.java

@Transactional
public UserResponse kakaoLogin(String authCode) {
    // 1. Authorization Code로 Access Token 요청 및 획득
    KakaoTokenResponse tokenResponse = getKakaoToken(authCode);

    // 2. Access Token으로 사용자 정보 요청 (카카오 고유 ID, 닉네임, 이메일 등)
    KakaoUserInfo userInfo = getKakaoUserInfo(tokenResponse.getAccessToken());

    // 3. 서비스 DB 연동 (카카오 ID를 서비스 userId로 사용)
    String kakaoUniqueId = String.valueOf(userInfo.getId());
    
    User user = authUserRepository.findByUserId(kakaoUniqueId)
            .orElseGet(() -> {
                // 3-1. DB에 해당 ID가 없으면, 자동 회원가입 (임시 비밀번호 설정)
                String tempPassword = passwordEncoder.encode(UUID.randomUUID().toString()); 
                
                User newUser = User.builder()
                        .userId(kakaoUniqueId) 
                        .username(userInfo.getNickname())
                        // 이메일 미제공 시 임시 이메일 사용
                        .email(userInfo.getKakaoAccount().getEmail() != null ? userInfo.getKakaoAccount().getEmail() : kakaoUniqueId + "@kakao.temp.com")
                        .password(tempPassword) // 💡 직접 로그인을 막기 위해 임시 비밀번호 암호화 저장
                        .role(Role.USER)
                        .useYn("Y")
                        .build();
                return authUserRepository.save(newUser);
            });

    // 4. 서비스 JWT 토큰 발급
    String serviceToken = jwtUtil.generateToken(user.getUserId());

    // 5. UserResponse DTO로 변환하여 프론트엔드에 응답
    return new UserResponse(user.getId(), user.getUserId(), user.getEmail(), user.getUsername(), serviceToken);
}

B. getKakaoToken (Access Token 요청)

RestTemplate을 사용하여 application/x-www-form-urlencoded 형식으로 카카오 토큰 서버에 POST 요청을 보냅니다.

// UserService.java (헬퍼 메서드)

private KakaoTokenResponse getKakaoToken(String authCode) {
    RestTemplate restTemplate = new RestTemplate();
    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

    MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
    params.add("grant_type", "authorization_code");
    params.add("client_id", kakaoRestApiKey);
    params.add("redirect_uri", kakaoRedirectUri);
    params.add("code", authCode); // 프론트에서 받은 인증 코드

    HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(params, headers);

    try {
        ResponseEntity<KakaoTokenResponse> response = restTemplate.exchange(
                kakaoTokenUri, HttpMethod.POST, request, KakaoTokenResponse.class
        );
        return response.getBody();

    } catch (HttpClientErrorException e) { 
        // 🚨 401 Unauthorized, 400 Invalid Grant 등 오류 발생 시
        log.error("카카오 토큰 발급 실패 (HTTP Error {}: {}): {}", e.getStatusCode(), e.getStatusText(), e.getResponseBodyAsString());
        throw new AccountInfoException("카카오 서버 통신 오류");
    }
}

저작자표시 (새창열림)