OAuth

개요

DataGSM OAuth는 OAuth 2.0 Authorization Code Grant 플로우를 기반으로 한 인증 시스템입니다. 사용자는 DataGSM 계정으로 서드파티 애플리케이션에 안전하게 로그인할 수 있으며, 애플리케이션은 사용자의 동의 하에 사용자 데이터에 접근할 수 있습니다. OAuth 2.0은 업계 표준 인증 프로토콜로, 사용자 비밀번호를 직접 공유하지 않고도 안전하게 리소스 접근 권한을 부여할 수 있습니다.

PKCE 도입 배경

PKCE (Proof Key for Code Exchange, RFC 7636)는 OAuth 2.0의 보안 확장 표준입니다. 전통적인 Authorization Code Flow에서는 client_secret을 사용하여 클라이언트를 인증했지만, 이는 다음과 같은 한계가 있습니다:

• 클라이언트 사이드 노출 위험: 브라우저나 모바일 앱에서 client_secret을 안전하게 보관하기 어려움
• Authorization Code 탈취 공격: 악의적인 앱이 가로챈 Authorization Code를 자신의 client_secret으로 교환 가능
• Public Client 보안 취약: SPA, 모바일 앱 등 Public Client에서는 secret 관리가 사실상 불가능

PKCE는 client_secret 대신 동적으로 생성되는 일회성 검증자(code_verifier)를 사용하여 이러한 문제를 해결합니다. 각 인증 요청마다 새로운 code_verifier를 생성하므로, Authorization Code를 탈취하더라도 원본 code_verifier 없이는 토큰 교환이 불가능합니다.

주요 특징

시스템 요구사항

기본 개념

Authorization Code

사용자 로그인 성공 시 발급되는 일회성 코드입니다. Access Token으로 교환되며, 5분의 유효기간을 가집니다.

Access Token

사용자 리소스에 접근하기 위한 JWT 토큰입니다. 1시간의 유효기간을 가지며, API 요청 시 Authorization: Bearer 헤더에 포함하여 사용합니다.

Refresh Token

Access Token 만료 시 새로운 Access Token을 발급받기 위한 토큰입니다. 30일의 유효기간을 가집니다.

Client Credentials

• Client ID: 애플리케이션을 식별하는 공개 식별자 (프론트엔드 사용 가능)
• Client Secret: 애플리케이션의 비밀 키 (기존 방식, PKCE도 선택 가능)

인증 플로우

DataGSM OAuth의 Authorization Code Grant 플로우는 다음과 같이 동작합니다.

인증 플로우는 다음 단계로 진행됩니다:

1. 사용자가 로그인 버튼 클릭
2. 클라이언트가 PKCE code_verifier 생성 및 저장 (43-128자 랜덤 문자열)
3. code_verifier를 SHA-256 해싱하여 code_challenge 생성
4. OAuth 서버로 인증 요청 (client_id, redirect_uri, code_challenge 포함)
5. 사용자가 로그인 페이지에서 이메일/비밀번호 입력
6. 인증 성공 시 Authorization Code 발급 및 리다이렉트
7. 클라이언트가 Token 교환 요청 (code, code_verifier 포함)
8. OAuth 서버가 PKCE 검증 (code_verifier 해싱 후 code_challenge와 비교)
9. 검증 성공 시 Access Token 및 Refresh Token 발급
10. Access Token으로 사용자 데이터 요청 및 로그인 완료

보안 가이드라인

OAuth 인증을 안전하게 구현하기 위한 주요 가이드라인입니다.

HTTPS 필수

모든 OAuth 통신은 반드시 HTTPS를 사용해야 합니다. HTTP는 토큰 탈취 위험이 있으므로 프로덕션 환경에서 사용 금지입니다. (개발 환경 localhost 예외)

PKCE 방식

PKCE는 Authorization Code 탈취 공격을 방지하는 보안 강화 방법 중 하나입니다. 사용하시는 경우 다음 사항을 참고하세요:

• code_verifier 생성: 43-128자의 안전한 랜덤 문자열 생성 (암호학적으로 안전한 난수 생성기 사용)
• code_challenge_method: 항상 S256 (SHA-256) 사용, plain은 보안상 취약
• 안전한 저장: code_verifier는 httpOnly 쿠키나 서버 세션에 저장 (localStorage/sessionStorage 지양)
• 일회성 사용: 각 인증 요청마다 새로운 code_verifier 생성

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

State 파라미터

CSRF 공격 방지를 위해 state 파라미터를 사용하세요. 랜덤 문자열을 생성하여 요청 시 전송하고, 콜백에서 검증합니다.

// State 생성 및 저장
const state = crypto.randomUUID();
sessionStorage.setItem('oauth_state', state);

// 인증 요청 시 포함
const authUrl = `https://oauth.data.hellogsm.kr/v1/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&state=${state}`;
window.location.href = authUrl;

// 콜백에서 검증
const urlParams = new URLSearchParams(window.location.search);
const returnedState = urlParams.get('state');
const savedState = sessionStorage.getItem('oauth_state');

if (returnedState !== savedState) {
  throw new Error('State mismatch - possible CSRF attack');
}

// 검증 후 state 삭제
sessionStorage.removeItem('oauth_state');

토큰 저장

Access Token은 메모리나 sessionStorage에, Refresh Token은 서버 측 세션이나 HttpOnly 쿠키에 저장하세요. localStorage는 XSS 공격에 취약하므로 사용을 지양합니다.

레거시 방식 (client_secret)

기존 애플리케이션의 하위 호환성을 위해 client_secret 방식을 지원하지만, 다음과 같은 보안 위험이 있습니다:

• 노출 위험: 프론트엔드 코드에 포함 시 쉽게 노출됨
• 관리 어려움: 주기적인 로테이션 및 안전한 저장이 어려움
• Public Client 부적합: SPA, 모바일 앱 등에서 사용 권장하지 않음

client_secret을 사용해야 하는 경우, 다음 사항을 반드시 준수하세요:

• 절대 프론트엔드 코드에 포함하거나 공개 저장소에 커밋하지 마세요
• 환경 변수나 보안 볼트에 안전하게 저장
• 주기적으로 로테이션
• 가능한 빠른 시일 내에 PKCE로 마이그레이션

시작하기

DataGSM OAuth를 사용하는 방법입니다.

PKCE 가이드 (권장)

PKCE를 사용한 안전한 OAuth 구현 방법을 배웁니다. 신규 애플리케이션은 여기서 시작하세요. PKCE 가이드

HTTP API

REST API를 직접 호출하여 구현합니다. 가장 유연하지만 구현 복잡도가 높습니다. HTTP API 기술 문서, 인증 흐름 시작, 토큰 교환, 토큰 갱신, 사용자 데이터 조회

SDK

공식 SDK를 사용하면 OAuth 플로우를 간단하게 구현할 수 있습니다. React SDK, Java/Kotlin SDK

실전 예제

프레임워크별 완전한 구현 예제를 제공합니다. React + Spring Boot (Kotlin)

API 엔드포인트

지원

OAuth 관련 문의는 GitHub Issues를 이용하세요. DataGSM Front Issues ↗, DataGSM Server Issues ↗