OAuth 구현 예제

개요

이 섹션에서는 다양한 프레임워크와 아키텍처 패턴을 사용한 실전 OAuth 구현 예제를 제공합니다. 각 예제는 완전히 동작하는 코드와 함께 프론트엔드와 백엔드 구현을 모두 포함합니다.

인증 방식 안내

PKCE 방식과 client_secret 방식 중 선택하실 수 있습니다. 새로운 프로젝트에서는 PKCE 방식을 고려해보시면 좋을 것 같습니다. 자세한 내용은 PKCE 가이드를 참고하세요.

사용 가능한 예제

예제	프론트엔드	백엔드	인증 방식	주요 특징	권장 사용 사례
React + Spring Boot (BFF)	React	Spring Boot (Kotlin)	PKCE	BFF 패턴, 서버에서 OAuth 처리, httpOnly 쿠키	보안이 가장 중요한 프로덕션 환경
Next.js + Spring Boot	Next.js	Spring Boot (Java)	PKCE	서버에서 token 교환 및 JWT 발급	엔터프라이즈 애플리케이션
React + Spring Boot (Kotlin)	React	Spring Boot (Kotlin)	client_secret (레거시)	프론트에서 token 교환, 서버에서 검증	SPA 기반 애플리케이션
Vanilla JS + NestJS	Vanilla JavaScript	NestJS (TypeScript)	client_secret (레거시)	세션 기반 인증	프레임워크 없는 프로젝트

시나리오별 선택 가이드

시나리오 1: React + Spring Boot (BFF)

언제 사용하나요?

프로덕션 환경에서 최고 수준의 보안이 필요한 경우
PKCE를 사용하여 Authorization Code 탈취를 방지하고 싶은 경우
토큰을 브라우저에 노출하지 않고 httpOnly 쿠키로 관리하고 싶은 경우

특징:

BFF(Backend For Frontend) 패턴 사용
서버에서 PKCE 플로우 처리 (code_verifier 생성 및 검증)
httpOnly 쿠키로 XSS 공격 방지
가장 안전한 구현 방식

플로우:

사용자 → React (BFF 엔드포인트 호출) → Spring Boot (PKCE + OAuth 처리 + httpOnly 쿠키 설정) → 로그인 완료

시나리오 2: Next.js + Spring Boot

언제 사용하나요?

Next.js SSR/SSG 기능을 활용하는 경우
서버 측에서 완전한 OAuth 플로우 제어가 필요한 경우
PKCE를 사용하여 보안을 강화하고 싶은 경우

특징:

프론트엔드는 Authorization Code만 획득
서버가 PKCE 검증 및 Token 교환 담당
안전한 구현 방식

플로우:

사용자 → Next.js (code 획득) → Spring Boot (PKCE 검증 + token 교환 + JWT 발급) → 로그인 완료

시나리오 3: React + Spring Boot (Kotlin) - 레거시

언제 사용하나요?

기존 프로젝트에서 client_secret 방식을 사용 중인 경우
PKCE로 마이그레이션하기 전 참고용

특징:

프론트엔드가 client_secret을 사용하여 Token 교환
서버는 Access Token을 검증하고 자체 JWT 발급
참고용 예제입니다

플로우:

사용자 → React (code 획득 + token 교환 with client_secret) → Spring Boot (token 검증 + JWT 발급) → 로그인 완료

시나리오 4: Vanilla JS + NestJS - 레거시

언제 사용하나요?

기존 프로젝트에서 client_secret 방식을 사용 중인 경우
프레임워크 없는 순수 JavaScript 프로젝트

특징:

프레임워크 없는 순수 JavaScript 구현
client_secret 방식 사용
서버 측 세션 스토어 활용

플로우:

사용자 → Vanilla JS (code 획득) → NestJS (token 교환 with client_secret + 세션 생성) → 로그인 완료

공통 개념

모든 예제는 다음 공통 개념을 포함합니다.

Client ID & Client Secret

DataGSM에서 발급받은 인증 데이터입니다.

Client ID: 프론트엔드에서 사용 가능
Client Secret: 반드시 서버에서만 사용 (절대 프론트엔드 노출 금지)

Authorization Code

사용자 인증 후 발급되는 일회성 코드입니다 (5분 유효).

Access Token & Refresh Token

Access Token: 사용자 리소스 접근용 (1시간 유효)
Refresh Token: Access Token 갱신용 (30일 유효)

리다이렉트 URI

OAuth 인증 후 사용자가 돌아올 URI입니다. DataGSM에 사전 등록되어야 합니다.

보안 권장사항

모든 예제에서 공통으로 적용해야 할 보안 권장사항입니다.

1. PKCE 사용

새로운 애플리케이션에서는 PKCE를 고려해보세요. Authorization Code 탈취 공격을 효과적으로 방지합니다.

// code_verifier 생성 (43-128자 랜덤 문자열)
const array = new Uint8Array(32);
crypto.getRandomValues(array);
const codeVerifier = base64UrlEncode(array);

// code_challenge 생성 (SHA-256 해시)
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const hash = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = base64UrlEncode(new Uint8Array(hash));

자세한 구현 방법은 PKCE 가이드를 참고하세요.

2. HTTPS 사용

프로덕션 환경에서는 반드시 HTTPS를 사용하세요.

3. State 파라미터

CSRF 공격 방지를 위해 State 파라미터를 사용하세요.

4. 토큰 저장

권장: httpOnly 쿠키 (XSS 공격 방지)
Access Token: 메모리 또는 sessionStorage
Refresh Token: httpOnly 쿠키 또는 서버 세션
지양: localStorage (XSS 공격에 취약)

5. Client Secret 보호 (레거시 방식 사용 시)

레거시 방식(client_secret)을 사용하는 경우에만 해당됩니다.

# 환경 변수로 관리
DATAGSM_CLIENT_SECRET=your-client-secret

# .gitignore에 추가
.env
.env.local

💡 새로운 프로젝트에서는 PKCE를 사용하시면 client_secret 관리가 불필요합니다.

예제 사용 방법

각 예제는 다음 구조로 제공됩니다.

아키텍처 개요: 전체 구조와 데이터 플로우
프론트엔드 구현: 완전한 코드와 설명
백엔드 구현: 완전한 코드와 설명
환경 설정: 필요한 환경 변수와 설정
실행 방법: 로컬 개발 환경 설정 가이드
플로우 다이어그램: 시각적 설명

다음 단계

프로젝트에 적합한 예제를 선택하여 구현을 시작하세요.

권장 (PKCE 사용):

레거시 (client_secret 사용):

PKCE 구현 방법이 필요하면 PKCE 가이드를 참고하세요. HTTP API 상세 기술 문서가 필요하면 HTTP API 기술 문서를 참고하세요.