[카카오 소셜 로그인] OAuth 2.0을 활용하여 카카오 소셜 로그인 적용 해보기 근데 이제 스프링을 곁들인..

 

카카오로 시작하기

프로젝트에 적용된 로그인 화면

---

현재 Jira, Slack과 유사한 협업 툴 플랫폼 프로젝트를 진행하고있다.
이 프로젝트에서는 JWT 자체 회원가입/로그인과 함께 OAuth 2.0을 활용한 카카오 소셜 로그인까지 모두 지원하도록 설계하고 있다.

오늘 포스팅에서, 카카오 소셜 로그인 기능을 어떻게 구현하는지 (OAuth 2.0의 인증 흐름부터, 실제 API 연동과 서버-프론트 처리까지)
직접 경험하며 배운 내용을 차근차근 정리해갈 예정이다.

 

🔐 OAuth 2.0 이란?

OAuth 2.0은 웹/앱 서비스가 사용자의 비밀번호를 직접 알지 않고 다른 서비스(카카오, 네이버, 구글 등)의 인증 정보를 이용해 안전하게 "인증" 및 "권한 위임"을 할 수 있게 해주는 업계 표준 프로토콜이다.

✅ 왜 필요할까?

• 비밀번호를 3rd-party 서비스에 직접 입력하지 않는다. → 보안 UP
• 카카오, 구글 등에서 인증하면 내 서비스에서는 간단하게 추가 정보만 받아서 회원가입/로그인 처리가 가능하다.

---

🔁 OAuth 2.0 기본 동작 흐름

OAuth 2.0 플로우는 [Client(우리 서비스)] - [사용자] - [3rd-party(카카오 등 인증 제공자)] 이 세 주체 사이에서 아래 단계로 동작한다.

1. 인가 요청 (Authorization Request)

• 사용자가 "카카오로 로그인" 버튼을 클릭한다.
• 우리 서비스가 카카오 인증 서버로 리다이렉트
• 요청 파라미터(클라이언트 ID, 리다이렉트 URL, scope 등)를 포함

GET https://kauth.kakao.com/oauth/authroize?client_id=xxx
    &redirect_url=xxx
    &response_type=code
    &scope=profile,email

 

2. 사용자 인증 & 인가

• 사용자는 카카오 로그인 페이지에서 로그인(로그인되어있으면 바로 진행)
• 서비스에 대해 사용자가 정보를 동의할지 여부 선택 → 동의/거부
• 동의하면 카카오가 인가 코드(authorization code)를 생성

3. 인가 코드 콜백(Redirect)

• 카카오는 리다이렉트 URL(우리 백엔드)에 code = 인가코드 파라미터로 GET 요청을 보냄.

GET /auth/kakao/callback?code=abcdef...

4. 토큰 발급 (Access Token Exchange)

• 우리 서버(백엔드)가 받은 인가코드로 카카오에게 POST 요청
• 카카오는 인가코드 확인 후 Access Token 또는 Refresh Token(선택)을 전달한다.

POST https://kauth.kakao.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=xxx
&redirect_uri=xxx
&code=abcdef...

5. API 호출(유저 정보 조회 등)

• 받은 Access Token을 사용해서 카카오 Open API 호출(ex. 유저 프로필/이메일 등)

GET https://kapi.kakao.com/v2/user/me
Authorization: Bearer {access_token}

6. 서비스 자체 로그인/회원가입 처리

• 이제부턴 우리 서비스의 로직으로 동작.
  • AccessToken으로 가져온 프로필 정보(KAKAO ID, EMAIL 등)로
    • 기존회원이면 바로 로그인 (JWT 발급)
    • 신규회원이면 추가 정보 입력(회원가입)

---

💻 실제 코드와 함께 보는 카카오 소셜 로그인 구현 순서

0. 프로젝트 환경

- BE: Spring Boot + JPA + Spring Security + MySQL

- FE: Next.js (React), TypeScript

 

1. 카카오 개발자 센터 애플리케이션 등록

1-1. 카카오 개발자 센터에서 애플리케이션 추가

 

1-2. REST API Key 발급

 

1-3. 동의 항목 설정

닉네임과 카카오계정을 동의항목으로 설정

 

1-4. Redirect URI 설정

카카오 로그인 후, 인증코드가 돌아올 리다이렉트 등록 (위에 개념3 참고)

---

2. 환경 설정 (yml, env, gradle)

2-1. build.gradle (dependencies 의존성 추가)

• 주요 의존성

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'com.fasterxml.jackson.core:jackson-databind'
implementation 'mysql:mysql-connector-java'
implementation 'org.projectlombok:lombok'
annotationProcessor 'org.projectlombok:lombok'

 

2-2. application.yml (local)

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/issue_mate
    username: ENC(${DB_USER_ENC})
    password: ENC(${DB_PW_ENC})
    driver-class-name: com.mysql.cj.jdbc.Driver

  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        #        show_sql: true
        format_sql: true
        default_batch_fetch_size: 100
    open-in-view: false

  data:
    redis:
      host: localhost
      port: 6379

#api_url: http://localhost:8080
next_public_base_url: http://localhost:3000

##kakao login
kakao:
  client:
    id: ${KAKAO_RESTAPIKEY}
  redirect:
    uri: ${KAKAO_REDIRECTURI}

 

2-3. .env

KAKAO_CLIENT_ID=여기에RESTAPI키
KAKAO_REDIRECT_URI=http://localhost:8080/auth/kakao/callback

---

3. Security Config 설정

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeHttpRequests()
                .requestMatchers("/auth/**", "/").permitAll()
                .anyRequest().authenticated();
        return http.build();
    }
}

• /auth/** 경로 모두 permitAll() → 카카오 콜백/회원가입 누구나 접근
• 나머지 경로는 인증 필요

---

4. BE: Entity / DTO 정의

4-1. USER Entity

@Entity
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class User {
    @Id @GeneratedValue
    @Column(name = "user_id")
    private Long id;

    @Column(nullable = false, unique = true)
    private String userEmail;
    private String password;
    private String name;
    private String phone;

    private String provider;   // "KAKAO", "LOCAL" 등
    private String providerId; // 카카오 고유 id

    private boolean termsAgreed;
    private String profile;
}

 

4-2. 카카오 관련 DTO

• KakaoLoginResultDto

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class KakaoLoginResultDto {
    private boolean newUser; // 신규회원 여부
    private String jwt;      // 기존회원이면 발급된 JWT
    private String kakaoId;
    private String email;
    private String name;
}

 

• KakaoSocialSignupDto

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class KakaoSocialSignUpdto {
    private String kakaoId;
    private String email;
    private String name;
    private String phone;
    private boolean termsAgreed;
}

• KakaoRegisterResponseDto

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class KakaoRegisterResponseDto {
    private String token;
    private String message;
}

 

---

5. BE: Service 구현

5-1. kakaoLoginResult(String code) Method

/**
 * 카카오 로그인: code로 access token 발급 → 유저정보 조회 → 회원여부 판별
 * @param code 인가코드
 */
    @Transactional(readOnly = true)
    public KakaoLoginResultDto kakaoLoginResult(String code) {
        log.info("[카카오 로그인] code로 accessToken 및 프로필 조회");

        // (1) 인가코드로 access token 요청
        String accessToken = getKakaoAccessToken(code);

        // (2) access token으로 유저 정보 조회
        KakaoUserInfoDto userInfo = getKakaoUserInfo(accessToken);

        log.info("[카카오 로그인] userInfo: kakaoId={}, email={}, name={}", userInfo.getKakaoId(), userInfo.getEmail(), userInfo.getName());

        // (3) DB에서 해당 provider/providerId 유저 조회
        User user = userRepository.findByProviderAndProviderId("KAKAO", userInfo.getKakaoId()).orElse(null);

        if (user == null) {
            // 신규 회원 → 추가정보 입력 필요
            return new KakaoLoginResultDto(true, null, userInfo.getKakaoId(), userInfo.getEmail(), userInfo.getName());
        }

        // 기존 회원 → JWT 발급
        String jwt = jwtProvider.generateToken("access", user.getUserEmail(), 360000L);
        return new KakaoLoginResultDto(false, jwt, null, null, null);
    }

• 인가코드로 토큰/유저 조회 후 신규/기존 회원 분기

5-2. kakaoRegister(KakaoSocialSignupDto) Method

   /**
    * 카카오 추가정보 입력 회원가입
    */
    @Transactional
    public String kakaoRegister(KakaoSocialSignUpdto signUpdto) {
        log.info("[카카오 회원가입] 시도: kakaoId={}, email={}, name={}", signUpdto.getKakaoId(), signUpdto.getEmail(), signUpdto.getName());

        // 중복가입 방지
        if (userRepository.findByProviderAndProviderId("KAKAO", signUpdto.getKakaoId()).isPresent()) {
            throw new IllegalArgumentException("이미 가입된 카카오 계정입니다.");
        }
        User user = createUserFromKakao(signUpdto);
        userRepository.save(user);

        // JWT 발급 후 반환
        String jwt = jwtProvider.generateToken("access", user.getUserEmail(), 360000L);
        return jwt;
    }

• 추가정보를 입력받아서 User 등록, JWT 발급

5-3. 기타 내부 메서드(getKakaoAccessToken, getKakaoUserInfo, createUserFromKakao)

 // --- 내부 메서드 ---

    /** 인가코드로 access token 획득 */
    private String getKakaoAccessToken(String code) {
        String tokenUrl = "https://kauth.kakao.com/oauth/token";
        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", clientId);
        params.add("redirect_uri", redirectUri);
        params.add("code", code);

        HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(params, headers);
        ResponseEntity<String> response = restTemplate.postForEntity(tokenUrl, request, String.class);

        try {
            JsonNode root = objectMapper.readTree(response.getBody());
            String accessToken = root.get("access_token").asText();
            return accessToken;
        } catch (Exception e) {
            throw new RuntimeException("카카오 access token 파싱 실패", e);
        }
    }

    /** access token으로 카카오 유저 정보 조회 */
    private KakaoUserInfoDto getKakaoUserInfo(String accessToken) {
        String userInfoUrl = "https://kapi.kakao.com/v2/user/me";
        RestTemplate restTemplate = new RestTemplate();

        HttpHeaders headers = new HttpHeaders();
        headers.setBearerAuth(accessToken);

        HttpEntity<?> request = new HttpEntity<>(headers);

        ResponseEntity<String> response = restTemplate.exchange(userInfoUrl, HttpMethod.GET, request, String.class);

        try {
            JsonNode root = objectMapper.readTree(response.getBody());
            JsonNode kakaoAccount = root.get("kakao_account");
            String kakaoId = root.get("id").asText();
            String email = kakaoAccount.get("email").asText();
            String name = kakaoAccount.get("profile").get("nickname").asText();
            return new KakaoUserInfoDto(email, name, kakaoId, null);
        } catch (Exception e) {
            throw new RuntimeException("카카오 사용자 정보 파싱 실패", e);
        }
    }

    /** 카카오 추가정보로 User 엔티티 생성 */
    private User createUserFromKakao(KakaoSocialSignUpdto dto) {
        return User.builder()
            .userEmail(dto.getEmail())
            .name(dto.getName())
            .phone(dto.getPhone())
            .provider("KAKAO")
            .providerId(dto.getKakaoId())
            .termsAgreed(dto.isTermsAgreed())
            .build();
    }
}

• getKakaoAccessToken(String Code): 인가코드로 Access Token 획득 - Oauth 개념 4 참고
• getKakaoUserInfo(String accessToken): Access Token으로 카카오 유저정보 조회 - Oauth 개념 5 참고
• createUserFormKakao(KakaoSocialSignUpDto): 카카오 + 추가정보로 User 엔티티 생성

---

6. BE: Contoller 구현

6-1. GET /kakao/login

 /**
  * 1. 카카오 로그인 인가 URL 리다이렉트
  */
    @GetMapping("/kakao/login")
    public void redirectToKakao(HttpServletResponse response) throws IOException {
        String url = "https://kauth.kakao.com/oauth/authorize"
            + "?client_id=" + kakaoClientId
            + "&redirect_uri=" + kakaoRedirectUri
            + "&response_type=code"
            + "&scope=account_email,profile_nickname";
        response.sendRedirect(url);
    }

• 인가 URL 생성 후 리다이렉트(카카오 로그인창으로)

6-2. GET /kakao/callback

 /**
  * 2. 인가코드 콜백 처리 (기존/신규 회원 분기)
  */
    @GetMapping("/kakao/callback")
    public void kakaoCallback(@RequestParam("code") String code, HttpServletResponse response) throws IOException {
        try {
            KakaoLoginResultDto result = kakaoAuthService.kakaoLoginResult(code);

            if (result.isNewUser()) {
                // 신규 회원 - 회원가입 폼으로 쿼리 전달
                String redirectUrl = String.format(
                    "http://localhost:3000/landing?signupNeeded=1&kakaoId=%s&email=%s&name=%s",
                    result.getKakaoId(), result.getEmail(), result.getName()
                );
                response.sendRedirect(redirectUrl);
            } else {
                // 기존 회원 - 바로 토큰 리다이렉트
                String redirectUrl = "http://localhost:3000/oauth-success?token=" + result.getJwt();
                response.sendRedirect(redirectUrl);
            }
        } catch (Exception e) {
            response.sendRedirect("http://localhost:3000/error?msg=" + e.getMessage());
        }
    }

• 인가코드로 로그인 처리, 신규/기존 분기

6-3. POST /kakao/register

    /**
     * 3. 카카오 회원가입(추가정보 입력)
     */
    @PostMapping("/kakao/register")
    public ResponseEntity<?> kakaoRegister(@RequestBody KakaoSocialSignUpdto signUpdto) {
        try {
            String jwt = kakaoAuthService.kakaoRegister(signUpdto);
            return ResponseEntity.ok().body(new KakaoRegisterResponseDto(jwt, "회원가입 성공"));
        } catch (IllegalArgumentException e) {
            return ResponseEntity.badRequest().body(new KakaoRegisterResponseDto(null, e.getMessage()));
        } catch (Exception e) {
            return ResponseEntity.internalServerError().body(new KakaoRegisterResponseDto(null, "서버 오류"));
        }
    }

• 추가정보 POST로 회원가입 처리

---

7. FE: 카카오 소셜로그인 플로우 (Next.js/React, TypeScript)

7-1. API 유틸 함수 (api/auth.ts, api/register.ts)

// 카카오 소셜 로그인 버튼 클릭
export function loginWithKakao() {
  window.location.href = "http://localhost:8080/auth/kakao/login";
}

// 카카오 회원가입
export async function registerKakaoUser(payload: KakaoSocialSignUpRequest): Promise<KakaoSocialSignUpResponse> {
  const response = await fetch("http://localhost:8080/auth/kakao/register", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  if (!response.ok) throw new Error((await response.json()).message || "회원가입 실패");
  return await response.json();
}

 

7-2. 회원가입 폼 컴포넌트 (SocialSignupForm.tsx)

import { useState } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import registerKakaoUser from "@/feature/social-signup/api/register";
import type { KakaoSocialSignUpRequest } from "@/feature/social-signup/types/signup.types";

export default function SocialSignupForm() {
  const router = useRouter();
  const searchParams = useSearchParams();

  // 쿼리 파라미터에서 provider, kakaoId, email 가져오기
  const provider = searchParams.get("provider");
  const kakaoId = searchParams.get("kakaoId");
  const email = searchParams.get("email");

  // 상태 관리
  const [name, setName] = useState("");
  const [phone, setPhone] = useState("");
  const [termsAgreed, setTermsAgreed] = useState(false);
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);

  // 폼 제출 핸들러
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError("");

    // 필수 입력값 체크
    if (!name || !phone || !termsAgreed) {
      setError("실명, 휴대폰번호, 약관동의 모두 필수입니다.");
      return;
    }

    setLoading(true);

    try {
      // API 요청에 사용할 데이터
      const payload: KakaoSocialSignUpRequest = {
        provider: provider ?? "kakao",
        kakaoId: kakaoId ?? undefined,
        email: email ?? undefined,
        name,
        phone,
        termsAgreed,
      };

      // 백엔드로 회원가입 API 호출
      const res = await registerKakaoUser(payload);
      localStorage.setItem("jwt_token", res.token);
      router.replace("/dashboard");
    } catch (err) {
      setError("회원가입에 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };

  // (아래는 UI 생략)
  // ...
}

• 카카오 로그인 버튼: 백엔드 인가 URL로 이동 (카카오 로그인 페이지)
• 콜백 URL: 회원여부에 따라 대시보드 or 회원가입 폼 리다이렉트
• 회원가입 폼: 실명, 휴대폰, 약관동의(필수) 입력
• 폼 제출: 유효성 검사 → 백엔드 API POST → JWT 저장, 대시보드 이동

 

 

---

 

이번 포스팅에서는 카카오 소셜 로그인을 실제로 프로젝트에 적용하는 전체 과정을 상세와 간단 그 사이 어디 쯤???? 으로 정리해보았다.

OAuth 2.0 기본 개념부터, 실제 Spring Boot와 React를 연동하여 로그인 및 회원가입을 처리하는 방법까지 많은 경험을 할 수 있었던 시간이었다.

직접 구현하며 얻은 경험을 통해 인증, API 보안, 프론트-백엔드 연동, 에러 처리 등 웹 서비스에서 필수적인 기술들을 더욱 깊이 이해할 수 있었다.

 

ℹ️ 참고 

[ - ]