SSO 쿠키/JWT 인증 시스템 완전 가이드 — 프레임워크별 실전 시리즈 인덱스

┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│ Browser  │     │  Frontend    │     │  Backend     │     │   IdP    │
│ (사용자)  │     │ (React/Next) │     │ (Spring/     │     │ (Keycloak│
│          │     │              │     │  Django)     │     │  Okta)   │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘     └────┬─────┘
     │  1. 로그인 클릭   │                    │                  │
     │─────────────────▶│                    │                  │
     │                  │  2. /auth/login    │                  │
     │                  │───────────────────▶│                  │
     │                  │                    │  3. Redirect URL │
     │                  │                    │─────────────────▶│
     │  4. IdP 로그인 페이지                  │                  │
     │◀──────────────────────────────────────────────────────────│
     │  5. 사용자 인증 (ID/PW, MFA)           │                  │
     │──────────────────────────────────────────────────────────▶│
     │                  │                    │  6. Auth Code    │
     │                  │                    │◀─────────────────│
     │                  │  7. Code → Token   │                  │
     │                  │◀───────────────────│                  │
     │                  │                    │  (id_token +     │
     │                  │                    │   access_token + │
     │                  │                    │   refresh_token) │
     │  8. Set-Cookie:  │                    │                  │
     │     access_token │                    │                  │
     │     (HttpOnly)   │                    │                  │
     │◀─────────────────│                    │                  │
     │  9. 인증 완료,    │                    │                  │
     │     대시보드 이동  │                    │                  │
     │◀─────────────────│                    │                  │

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│ Browser  │     │  Frontend    │     │  Backend     │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘
     │  API 요청         │                    │
     │─────────────────▶│                    │
     │                  │  Cookie 자동 전송   │
     │                  │  (access_token)    │
     │                  │───────────────────▶│
     │                  │                    │  JWT 검증
     │                  │                    │  (서명, 만료, 클레임)
     │                  │   200 + 데이터     │
     │                  │◀───────────────────│
     │  렌더링           │                    │
     │◀─────────────────│                    │

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│ Browser  │     │  Frontend    │     │  Backend     │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘
     │  API 요청         │                    │
     │─────────────────▶│                    │
     │                  │  Cookie 전송        │
     │                  │───────────────────▶│
     │                  │   401 Unauthorized │
     │                  │◀───────────────────│
     │                  │                    │
     │                  │  POST /auth/refresh│
     │                  │  (refresh_token    │
     │                  │   Cookie 전송)     │
     │                  │───────────────────▶│
     │                  │   새 access_token  │
     │                  │   Set-Cookie       │
     │                  │◀───────────────────│
     │                  │                    │
     │                  │  원래 요청 재시도    │
     │                  │───────────────────▶│
     │                  │   200 + 데이터     │
     │                  │◀───────────────────│
     │  렌더링           │                    │
     │◀─────────────────│                    │

┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│ Browser  │     │  Frontend    │     │  Backend     │     │   IdP    │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘     └────┬─────┘
     │  로그아웃 클릭     │                    │                  │
     │─────────────────▶│                    │                  │
     │                  │  POST /auth/logout │                  │
     │                  │───────────────────▶│                  │
     │                  │                    │  Revoke Token    │
     │                  │                    │─────────────────▶│
     │                  │   Set-Cookie:      │                  │
     │                  │   access_token=""  │                  │
     │                  │   Max-Age=0        │                  │
     │                  │◀───────────────────│                  │
     │  쿠키 삭제,       │                    │                  │
     │  로그인 페이지     │                    │                  │
     │◀─────────────────│                    │                  │

Set-Cookie: access_token=eyJhbGciOi...;
  HttpOnly;
  Secure;
  SameSite=Lax;
  Path=/;
  Max-Age=900;
  Domain=.myservice.com

Set-Cookie: refresh_token=dGhpcyBpcyBh...;
  HttpOnly;
  Secure;
  SameSite=Strict;
  Path=/api/auth/refresh;
  Max-Age=604800;
  Domain=.myservice.com

Set-Cookie: csrf_token=abc123def456;
  Secure;
  SameSite=Lax;
  Path=/;
  Max-Age=900;
  Domain=.myservice.com

SSO(크로스 도메인) 필요?
├── Yes → SameSite=None; Secure (+ CSRF Token 필수)
└── No
    ├── 외부 링크에서 유입 시 로그인 유지 필요?
    │   ├── Yes → SameSite=Lax
    │   └── No  → SameSite=Strict
    └── API 전용 쿠키?
        └── SameSite=Strict (가장 안전)

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.    ← Header (Base64URL)
eyJzdWIiOiJ1c2VyMTIzIiwicm9sZXMiOlsiQU... ← Payload (Base64URL)
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQ... ← Signature

{
  "alg": "RS256", // 서명 알고리즘 (RS256, HS256, ES256 등)
  "typ": "JWT", // 토큰 타입
  "kid": "key-id-001" // Key ID (JWK Set에서 공개키 식별용)
}

{
  "sub": "user123", // Subject — 사용자 고유 식별자
  "iss": "https://idp.myservice.com", // Issuer — 토큰 발급자
  "aud": "https://api.myservice.com", // Audience — 토큰 수신 대상
  "exp": 1741420800, // Expiration — 만료 시각 (Unix timestamp)
  "iat": 1741417200, // Issued At — 발급 시각
  "nbf": 1741417200, // Not Before — 이 시각 이전에는 무효
  "jti": "unique-token-id-789", // JWT ID — 토큰 고유 ID (재사용 방지)
  "roles": ["ADMIN", "USER"], // Custom — 사용자 권한
  "tenant_id": "tenant-abc", // Custom — 멀티테넌트 식별
  "email": "user@example.com" // Custom — 사용자 이메일
}

RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  publicKey
)

import base64, json

def parse_jwt(token):
    header_b64, payload_b64, signature = token.split(".")

    # Base64URL 디코딩 (패딩 보정)
    header = json.loads(
        base64.urlsafe_b64decode(header_b64 + "==")
    )
    payload = json.loads(
        base64.urlsafe_b64decode(payload_b64 + "==")
    )

    # 만료 검증
    import time
    if payload["exp"] < time.time():
        raise Exception("토큰이 만료되었습니다")

    # 발급자 검증
    if payload["iss"] != "https://idp.myservice.com":
        raise Exception("신뢰할 수 없는 발급자입니다")

    return header, payload

// credentials: 'include'가 핵심
const response = await fetch('https://api.myservice.com/users/me', {
  method: 'GET',
  credentials: 'include', // 쿠키를 포함하여 전송
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': getCsrfToken(), // CSRF 토큰 헤더
  },
})

const api = axios.create({
  baseURL: 'https://api.myservice.com',
  withCredentials: true, // 쿠키를 포함하여 전송
})

// 인터셉터로 CSRF 토큰 자동 첨부
api.interceptors.request.use((config) => {
  const csrfToken = getCookieValue('csrf_token')
  if (csrfToken) {
    config.headers['X-CSRF-Token'] = csrfToken
  }
  return config
})

Access-Control-Allow-Origin: https://app.myservice.com   ← 정확한 Origin
Access-Control-Allow-Credentials: true                    ← 필수
Access-Control-Allow-Headers: Content-Type, X-CSRF-Token ← 커스텀 헤더 허용
Access-Control-Allow-Methods: GET, POST, PUT, DELETE      ← 허용 메서드
Access-Control-Expose-Headers: X-Request-Id               ← 프론트에서 읽을 헤더

# 이렇게 하면 브라우저가 차단합니다
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
# → 에러: credentials 모드에서는 와일드카드 Origin 불가

# Django 예시
ALLOWED_ORIGINS = [
    'https://app.myservice.com',
    'https://admin.myservice.com',
]

# django-cors-headers 설정
CORS_ALLOWED_ORIGINS = ALLOWED_ORIGINS
CORS_ALLOW_CREDENTIALS = True

# Preflight(OPTIONS) 요청에는 쿠키가 포함되지 않습니다!
# OPTIONS 응답에서 인증을 요구하면 안 됩니다.
# → Backend의 인증 필터에서 OPTIONS 메서드를 제외하세요.

# 프론트: https://app.myservice.com
# 백엔드: https://api.myservice.com
# → 서로 다른 Origin이므로 SameSite=Strict 쿠키는 전송되지 않습니다
# → SameSite=None; Secure 또는 같은 상위 도메인 사용

# localhost:3000 → localhost:8080 : 같은 사이트 (쿠키 전송됨)
# localhost:3000 → 127.0.0.1:8080 : 다른 사이트! (쿠키 전송 안됨)
# → 개발 환경에서도 동일한 호스트명을 사용하세요

# JWT Payload 디코딩 (누구나 가능)
echo "eyJzdWIiOiJ1c2VyMTIzIn0" | base64 -d
# 출력: {"sub":"user123"}

// 위험한 패턴
localStorage.setItem('token', jwt)

// 안전한 패턴: HttpOnly Cookie 사용 (서버에서 설정)
// 프론트엔드는 토큰을 직접 다루지 않음

# GET /api/users/delete?id=123  ← 이런 API는 SameSite=Lax로도 방어 불가!
# → 상태 변경은 반드시 POST/PUT/DELETE로 설계하세요

# CORS와 무관하게 동작
curl -X POST https://api.myservice.com/data \
  -H "Cookie: access_token=stolen_token"
# → 서버 측 토큰 검증이 반드시 필요합니다

// 해결: 갱신 요청을 하나로 모으는 패턴
let refreshPromise = null

async function refreshToken() {
  if (refreshPromise) return refreshPromise // 이미 갱신 중이면 대기

  refreshPromise = axios.post('/auth/refresh').finally(() => {
    refreshPromise = null
  })

  return refreshPromise
}