OAuth2 Authorization Code Grant Type 실습 (TypeScript)

웹개발 입문자들을 위한 OAuth2 Authorization Code Grant Type 실습 자료입니다. TypeScript로 타입 안전성을 확보하고, 실습 과제로 직접 코드를 완성하는 방식으로 구성되어 있습니다.

프로젝트 구조

OAuth-practice/
├── client/          # React 클라이언트 애플리케이션 (TypeScript)
├── server/          # Express 서버 애플리케이션 (TypeScript)
├── docs/           # 단계별 실습 문서
└── README.md       # 이 파일

실습 개요

이 실습에서는 다음과 같은 OAuth2 Authorization Code Grant Type의 전체 플로우를 TypeScript로 타입 안전하게 구현합니다:

1. Authorization Code 요청 - 사용자를 OAuth 제공자로 리다이렉트
2. 토큰 발급 - Authorization Code를 Access Token으로 교환
3. 프로필 요청 - Access Token으로 사용자 정보 조회
4. 유저 생성/조회 - IDP 식별자로 내부 유저 관리
5. JWT 발급 - 내부 인증을 위한 JWT 토큰 생성
6. OpenID Connect - (참고용 전체 코드 제공)

🎯 실습 방식

기존 방식 vs 새로운 방식

• 기존: 완성된 코드 제공 → 실행 → 결과 확인
• 새로운: TODO 주석과 타입 힌트 제공 → 직접 구현 → 단계별 완성

실습 과제

서버 코드(server/src/index.ts)에서 다음 과제들을 직접 구현합니다:

1. 🎯 과제 1: Google OAuth 인증 URL 생성 및 리다이렉트
2. 🎯 과제 2: Authorization Code를 Access Token으로 교환
3. 🎯 과제 3: Access Token으로 사용자 정보 조회
4. 🎯 과제 4: IDP 식별자로 내부 유저 생성/관리
5. 🎯 과제 5: 내부 인증을 위한 JWT 토큰 생성
6. 🎯 추가 과제: 사용자 정보 업데이트 API 구현

기술 스택

• Frontend: React + TypeScript + Axios
• Backend: Express.js + TypeScript + Node.js
• Database: 메모리 저장소 (실습용)
• OAuth Provider: Google OAuth 2.0
• 타입 안전성: TypeScript 인터페이스 및 타입 정의

시작하기

1. 의존성 설치

# 서버 의존성 설치
cd server
npm install

# 클라이언트 의존성 설치
cd ../client
npm install

2. 환경 변수 설정

서버의 .env 파일을 생성하고 Google OAuth 정보를 입력하세요:

cd server
cp .env.example .env
# .env 파일에 Google OAuth 정보 입력

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
JWT_SECRET=your_jwt_secret

3. 실습 진행

3.1 개발 서버 시작

# 서버 실행 (TypeScript 개발 모드)
cd server
npm run dev

# 클라이언트 실행 (새 터미널)
cd client
npm start

3.2 실습 과제 수행

1. server/src/index.ts 파일 열기
2. TODO 주석(🎯 실습 과제 X) 찾기
3. 타입 힌트를 참고하여 코드 작성
4. 저장하면 자동으로 서버 재시작
5. 브라우저에서 테스트

3.3 실습 순서

1. Step 1: 기본 환경 설정 (TypeScript)
2. Step 2: Authorization Code 요청
3. Step 3: 토큰 교환
4. Step 4: 프로필 요청
5. Step 5: 유저 관리
6. Step 6: JWT 발급
7. Step 7: OpenID Connect (참고)

4. 애플리케이션 실행

# 서버 실행 (포트 3001)
cd server
npm run dev

# 클라이언트 실행 (포트 3000)
cd client
npm start

TypeScript 장점

1. 타입 안전성

// API 응답 타입이 보장됨
const tokenResponse: AxiosResponse<GoogleTokenResponse> = await axios.post(...);
const { access_token, token_type }: GoogleTokenResponse = tokenResponse.data;

// 사용자 객체 구조가 명확함
const user: User = {
  id: generateUserId(),
  email: userInfo.email,
  name: userInfo.name,
  // ...
};

2. 개발 경험 향상

• IDE에서 자동완성 및 타입 검사
• 컴파일 타임 오류 감지
• 리팩토링 시 안전성 보장

3. 실습 도움

• 타입 정의가 구현 힌트 역할
• 올바른 데이터 구조 사용 강제
• API 스펙 문서화 효과

Google OAuth 2.0 설정

1. Google Cloud Console에서 새 프로젝트 생성
2. OAuth 2.0 클라이언트 ID 생성
3. 승인된 리디렉션 URI 추가: http://localhost:3001/auth/callback
4. 클라이언트 ID와 시크릿을 .env 파일에 추가

학습 목표

• OAuth2 Authorization Code Grant Type의 전체 플로우 이해
• TypeScript를 활용한 타입 안전한 웹 개발
• 프론트엔드와 백엔드 간의 인증 처리 방식 학습
• 보안 토큰 관리 및 JWT 활용법 습득
• 실제 서비스에서 사용되는 소셜 로그인 구현 방식 체험
• 직접 코딩을 통한 실무 경험 습득

실습 완료 확인

모든 과제를 완료하면 다음이 가능해집니다:

1. ✅ Google 로그인 버튼 클릭
2. ✅ Google OAuth 페이지 리다이렉트
3. ✅ 로그인 완료 후 콜백 처리
4. ✅ 사용자 정보 표시
5. ✅ JWT 토큰으로 API 호출
6. ✅ TypeScript 타입 안전성 확보

주의사항

• 이 프로젝트는 학습 목적으로 만들어졌으며, 프로덕션 환경에서는 추가적인 보안 조치가 필요합니다.
• 실습용으로 메모리 저장소를 사용하므로 서버 재시작 시 데이터가 초기화됩니다.
• TypeScript 컴파일 에러가 있으면 서버가 시작되지 않으니 타입을 정확히 맞춰주세요.