OAuth 2.0 Grant Types 완벽 가이드

// 위치: 클라이언트 (브라우저/모바일 앱)
// 시점: Authorization 요청 직전
// 43-128자의 랜덤 문자열 생성
const codeVerifier = generateRandomString(128);
// 예: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
 
// ⚠️ 이 값은 클라이언트에만 저장하고 절대 서버로 보내지 않습니다!
sessionStorage.setItem('code_verifier', codeVerifier);

// 위치: 클라이언트 (브라우저/모바일 앱)
// 시점: Authorization 요청 직전
// code_verifier를 SHA256으로 해싱
const hash = await crypto.subtle.digest('SHA-256',
  new TextEncoder().encode(codeVerifier)
);
const codeChallenge = base64UrlEncode(hash);
// 예: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
 
// 이 해시 값은 공개되어도 원본(code_verifier)을 알 수 없음 (일방향 해시)

위치: 클라이언트 → Authorization Server
시점: 사용자가 로그인 버튼을 클릭했을 때

GET https://auth.example.com/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  redirect_uri=https://app.example.com/callback&
  scope=read write&
  state=xyz&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256

⚠️ code_challenge는 URL에 노출되어도 안전 (해시 값이므로 역산 불가능)
⚠️ code_verifier는 절대 전송하지 않음!

위치: Authorization Server
시점: Authorization 요청을 받았을 때

저장 형식:
{
  "authorization_code": "abc123...",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256",
  "client_id": "CLIENT_ID",
  "expires_at": "2025-11-25T12:30:00Z"
}

이 code_challenge는 나중에 검증할 때 사용됩니다.

위치: 클라이언트 → Authorization Server
시점: Authorization Code를 받은 직후 (콜백 처리 시)

POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=CLIENT_ID&
redirect_uri=https://app.example.com/callback&
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

⚠️ 이제야 원본 code_verifier를 전송합니다 (HTTPS로 암호화됨)

// 위치: Authorization Server
// 시점: Token 요청을 받았을 때
 
// 1. 저장된 code_challenge 가져오기
const storedChallenge = database.getCodeChallenge(authorizationCode);
// "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
 
// 2. 받은 code_verifier를 SHA256으로 해싱
const receivedVerifier = request.body.code_verifier;
// "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
 
const computedChallenge = base64UrlEncode(
  sha256(receivedVerifier)
);
// "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
 
// 3. 비교
if (computedChallenge === storedChallenge) {
  // ✅ 검증 성공: 같은 클라이언트임이 확인됨
  return issueAccessToken();
} else {
  // ❌ 검증 실패: 공격자가 중간에 가로챈 것으로 의심
  return { error: 'invalid_grant' };
}

POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded
 
# 아래 파라미터들은 HTTP Request Body에 포함됩니다
grant_type=client_credentials&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET&
scope=api.read api.write

POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
 
# Request Body에는 grant_type과 scope만 포함
grant_type=client_credentials&
scope=api.read api.write

# 환경 변수 사용
export CLIENT_SECRET="your-secret-here"
 
# 비밀 관리 시스템 사용
# - AWS Secrets Manager
# - HashiCorp Vault
# - Azure Key Vault
# - Google Secret Manager

{
  "scope": "api.read",  // ✅ 읽기만 필요한 경우
  "scope": "api.*"      // ❌ 과도한 권한
}

{
  "access_token": "...",
  "expires_in": 3600,  // 1시간
  "token_type": "Bearer"
}

POST https://auth.example.com/device/code
Content-Type: application/x-www-form-urlencoded
 
client_id=CLIENT_ID&
scope=read write

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com/device",
  "verification_uri_complete": "https://example.com/device?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&
client_id=CLIENT_ID

// ✅ 올바른 방법
const codeVerifier = generateRandomString(128);
const codeChallenge = base64UrlEncode(sha256(codeVerifier));
 
// Authorization 요청에 포함
authorizeUrl += `&code_challenge=${codeChallenge}`;
authorizeUrl += `&code_challenge_method=S256`;

{
  "access_token": "...",
  "expires_in": 900,  // ✅ 15분
  "refresh_token": "...",
  "refresh_token_expires_in": 2592000  // 30일
}

// Token 갱신 시
const response = await fetch('https://auth.example.com/token', {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: oldRefreshToken,
    client_id: CLIENT_ID
  })
});
 
const { access_token, refresh_token } = await response.json();
 
// ✅ 새로운 refresh_token 저장
// ✅ 이전 refresh_token 무효화

// Authorization 요청 전
const state = generateRandomString(32);
sessionStorage.setItem('oauth_state', state);
 
// 콜백 처리 시
const returnedState = urlParams.get('state');
const savedState = sessionStorage.getItem('oauth_state');
 
if (returnedState !== savedState) {
  throw new Error('CSRF attack detected');
}

{
  "client_id": "abc123",
  "redirect_uris": [
    "https://app.example.com/callback"  // ✅ 정확한 매칭
  ]
}

{
  "redirect_uris": [
    "https://*.example.com/callback",  // ❌ 와일드카드
    "http://localhost:3000/callback"   // ❌ HTTP (개발 환경 제외)
  ]
}

// ❌ 절대 금지
localStorage.setItem('access_token', token);  // XSS 취약
sessionStorage.setItem('access_token', token);  // XSS 취약
 
// ✅ 권장 방법 1: HttpOnly Cookie (서버에서 설정)
Set-Cookie: access_token=...; HttpOnly; Secure; SameSite=Strict
 
// ✅ 권장 방법 2: 메모리에만 저장
let accessToken = null;  // 변수에만 저장, 새로고침 시 재인증

// iOS: Keychain
let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as String: "access_token",
    kSecValueData as String: token.data(using: .utf8)!
]
SecItemAdd(query as CFDictionary, nil)

// Android: Encrypted SharedPreferences
val masterKey = MasterKey.Builder(context)
    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
    .build()
 
val sharedPreferences = EncryptedSharedPreferences.create(
    context,
    "secret_shared_prefs",
    masterKey,
    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)
 
sharedPreferences.edit().putString("access_token", token).apply()

# Nginx 설정
server {
    listen 443 ssl http2;
    server_name auth.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # HTTP 요청을 HTTPS로 리다이렉트
    if ($scheme != "https") {
        return 301 https://$server_name$request_uri;
    }
}

// ❌ 과도한 권한
scope: "read write delete admin"
 
// ✅ 필요한 권한만
scope: "read:posts write:posts"

// Resource Server에서 토큰 검증
async function validateToken(token) {
  // 1. 토큰 서명 검증 (JWT 사용 시)
  const decoded = jwt.verify(token, PUBLIC_KEY);
  
  // 2. 만료 시간 확인
  if (decoded.exp < Date.now() / 1000) {
    throw new Error('Token expired');
  }
  
  // 3. Scope 확인
  if (!decoded.scope.includes('required:permission')) {
    throw new Error('Insufficient permissions');
  }
  
  // 4. 토큰 무효화 목록 확인 (옵션)
  const isRevoked = await checkRevokedTokens(decoded.jti);
  if (isRevoked) {
    throw new Error('Token revoked');
  }
  
  return decoded;
}

// 1. PKCE 생성 함수
function generateRandomString(length) {
  const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
  const randomValues = new Uint8Array(length);
  crypto.getRandomValues(randomValues);
  return Array.from(randomValues)
    .map(v => charset[v % charset.length])
    .join('');
}
 
async function sha256(plain) {
  const encoder = new TextEncoder();
  const data = encoder.encode(plain);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return hash;
}
 
function base64UrlEncode(arrayBuffer) {
  const bytes = new Uint8Array(arrayBuffer);
  const binary = String.fromCharCode(...bytes);
  const base64 = btoa(binary);
  return base64
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}
 
// 2. Authorization 요청
async function initiateOAuth() {
  // PKCE 파라미터 생성
  const codeVerifier = generateRandomString(128);
  const codeChallenge = base64UrlEncode(await sha256(codeVerifier));
  const state = generateRandomString(32);
  
  // 세션 저장
  sessionStorage.setItem('code_verifier', codeVerifier);
  sessionStorage.setItem('oauth_state', state);
  
  // Authorization URL 생성
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'YOUR_CLIENT_ID',
    redirect_uri: 'https://app.example.com/callback',
    scope: 'openid profile email',
    state: state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256'
  });
  
  // 리다이렉트
  window.location.href = `https://auth.example.com/authorize?${params}`;
}
 
// 3. 콜백 처리
async function handleCallback() {
  const urlParams = new URLSearchParams(window.location.search);
  const code = urlParams.get('code');
  const state = urlParams.get('state');
  
  // State 검증 (CSRF 방지)
  const savedState = sessionStorage.getItem('oauth_state');
  if (state !== savedState) {
    throw new Error('State mismatch - possible CSRF attack');
  }
  
  // Code Verifier 가져오기
  const codeVerifier = sessionStorage.getItem('code_verifier');
  
  // Token 교환
  const response = await fetch('https://auth.example.com/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: 'https://app.example.com/callback',
      client_id: 'YOUR_CLIENT_ID',
      code_verifier: codeVerifier
    })
  });
  
  const tokens = await response.json();
  
  // 토큰 저장 (메모리에만 - 보안)
  // sessionStorage/localStorage 사용 금지!
  window.accessToken = tokens.access_token;
  window.refreshToken = tokens.refresh_token;
  
  // 세션 정리
  sessionStorage.removeItem('code_verifier');
  sessionStorage.removeItem('oauth_state');
  
  return tokens;
}
 
// 4. API 요청
async function fetchUserData() {
  const response = await fetch('https://api.example.com/user', {
    headers: {
      'Authorization': `Bearer ${window.accessToken}`
    }
  });
  
  if (response.status === 401) {
    // Token 만료 - refresh 시도
    await refreshAccessToken();
    return fetchUserData(); // 재시도
  }
  
  return response.json();
}
 
// 5. Token 갱신
async function refreshAccessToken() {
  const response = await fetch('https://auth.example.com/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: window.refreshToken,
      client_id: 'YOUR_CLIENT_ID'
    })
  });
  
  const tokens = await response.json();
  window.accessToken = tokens.access_token;
  window.refreshToken = tokens.refresh_token; // Rotation
}

// oauth-client.js
const axios = require('axios');
 
class OAuthClient {
  constructor(config) {
    this.clientId = config.clientId;
    this.clientSecret = config.clientSecret;
    this.tokenEndpoint = config.tokenEndpoint;
    this.accessToken = null;
    this.expiresAt = null;
  }
  
  async getAccessToken() {
    // 유효한 토큰이 있으면 재사용
    if (this.accessToken && Date.now() < this.expiresAt) {
      return this.accessToken;
    }
    
    // 새 토큰 요청
    const response = await axios.post(
      this.tokenEndpoint,
      new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: 'api.read api.write'
      }),
      {
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        }
      }
    );
    
    const { access_token, expires_in } = response.data;
    
    this.accessToken = access_token;
    // 만료 5분 전에 갱신 (버퍼)
    this.expiresAt = Date.now() + (expires_in - 300) * 1000;
    
    return this.accessToken;
  }
  
  async makeAuthenticatedRequest(url, options = {}) {
    const token = await this.getAccessToken();
    
    return axios({
      ...options,
      url,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`
      }
    });
  }
}
 
// 사용 예시
const oauthClient = new OAuthClient({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  tokenEndpoint: 'https://auth.example.com/token'
});
 
// API 호출
const userData = await oauthClient.makeAuthenticatedRequest(
  'https://api.example.com/users/123',
  { method: 'GET' }
);