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

┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│ Browser  │     │  Frontend    │     │  Backend     │     │   IdP    │
│ (User)   │     │ (React/Next) │     │ (Spring/     │     │ (Keycloak│
│          │     │              │     │  Django)     │     │  Okta)   │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘     └────┬─────┘
     │  1. Click login  │                    │                  │
     │─────────────────▶│                    │                  │
     │                  │  2. /auth/login    │                  │
     │                  │───────────────────▶│                  │
     │                  │                    │  3. Redirect URL │
     │                  │                    │─────────────────▶│
     │  4. IdP login page                    │                  │
     │◀──────────────────────────────────────────────────────────│
     │  5. User authentication (ID/PW, MFA)  │                  │
     │──────────────────────────────────────────────────────────▶│
     │                  │                    │  6. Auth Code    │
     │                  │                    │◀─────────────────│
     │                  │  7. Code → Token   │                  │
     │                  │◀───────────────────│                  │
     │                  │                    │  (id_token +     │
     │                  │                    │   access_token + │
     │                  │                    │   refresh_token) │
     │  8. Set-Cookie:  │                    │                  │
     │     access_token │                    │                  │
     │     (HttpOnly)   │                    │                  │
     │◀─────────────────│                    │                  │
     │  9. Auth complete,│                    │                  │
     │     go to dashboard│                   │                  │
     │◀─────────────────│                    │                  │

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│ Browser  │     │  Frontend    │     │  Backend     │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘
     │  API request      │                    │
     │─────────────────▶│                    │
     │                  │  Cookie auto-sent   │
     │                  │  (access_token)    │
     │                  │───────────────────▶│
     │                  │                    │  JWT verification
     │                  │                    │  (signature, expiry, claims)
     │                  │   200 + data       │
     │                  │◀───────────────────│
     │  Render           │                    │
     │◀─────────────────│                    │

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│ Browser  │     │  Frontend    │     │  Backend     │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘
     │  API request      │                    │
     │─────────────────▶│                    │
     │                  │  Cookie sent        │
     │                  │───────────────────▶│
     │                  │   401 Unauthorized │
     │                  │◀───────────────────│
     │                  │                    │
     │                  │  POST /auth/refresh│
     │                  │  (refresh_token    │
     │                  │   Cookie sent)     │
     │                  │───────────────────▶│
     │                  │   New access_token │
     │                  │   Set-Cookie       │
     │                  │◀───────────────────│
     │                  │                    │
     │                  │  Retry original    │
     │                  │  request           │
     │                  │───────────────────▶│
     │                  │   200 + data       │
     │                  │◀───────────────────│
     │  Render           │                    │
     │◀─────────────────│                    │

┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│ Browser  │     │  Frontend    │     │  Backend     │     │   IdP    │
└────┬─────┘     └──────┬───────┘     └──────┬───────┘     └────┬─────┘
     │  Click logout     │                    │                  │
     │─────────────────▶│                    │                  │
     │                  │  POST /auth/logout │                  │
     │                  │───────────────────▶│                  │
     │                  │                    │  Revoke Token    │
     │                  │                    │─────────────────▶│
     │                  │   Set-Cookie:      │                  │
     │                  │   access_token=""  │                  │
     │                  │   Max-Age=0        │                  │
     │                  │◀───────────────────│                  │
     │  Cookie deleted,  │                    │                  │
     │  login page       │                    │                  │
     │◀─────────────────│                    │                  │

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

Need SSO (cross-domain)?
├── Yes → SameSite=None; Secure (+ CSRF Token required)
└── No
    ├── Need to maintain login when arriving via external link?
    │   ├── Yes → SameSite=Lax
    │   └── No  → SameSite=Strict
    └── API-only cookie?
        └── SameSite=Strict (most secure)

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

{
  "alg": "RS256", // Signing algorithm (RS256, HS256, ES256, etc.)
  "typ": "JWT", // Token type
  "kid": "key-id-001" // Key ID (for identifying public key in JWK Set)
}

{
  "sub": "user123", // Subject — unique user identifier
  "iss": "https://idp.myservice.com", // Issuer — token issuer
  "aud": "https://api.myservice.com", // Audience — intended recipient
  "exp": 1741420800, // Expiration — expiry time (Unix timestamp)
  "iat": 1741417200, // Issued At — issuance time
  "nbf": 1741417200, // Not Before — invalid before this time
  "jti": "unique-token-id-789", // JWT ID — unique token ID (replay prevention)
  "roles": ["ADMIN", "USER"], // Custom — user permissions
  "tenant_id": "tenant-abc", // Custom — multi-tenant identifier
  "email": "user@example.com" // Custom — user email
}

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

import base64, json

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

    # Base64URL decoding (padding correction)
    header = json.loads(
        base64.urlsafe_b64decode(header_b64 + "==")
    )
    payload = json.loads(
        base64.urlsafe_b64decode(payload_b64 + "==")
    )

    # Expiry verification
    import time
    if payload["exp"] < time.time():
        raise Exception("Token has expired")

    # Issuer verification
    if payload["iss"] != "https://idp.myservice.com":
        raise Exception("Untrusted issuer")

    return header, payload

// credentials: 'include' is the key
const response = await fetch('https://api.myservice.com/users/me', {
  method: 'GET',
  credentials: 'include', // Send cookies along
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': getCsrfToken(), // CSRF token header
  },
})

const api = axios.create({
  baseURL: 'https://api.myservice.com',
  withCredentials: true, // Send cookies along
})

// Auto-attach CSRF token via interceptor
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   ← Exact Origin
Access-Control-Allow-Credentials: true                    ← Required
Access-Control-Allow-Headers: Content-Type, X-CSRF-Token ← Allow custom headers
Access-Control-Allow-Methods: GET, POST, PUT, DELETE      ← Allowed methods
Access-Control-Expose-Headers: X-Request-Id               ← Headers readable by frontend

# This will be blocked by the browser
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
# → Error: Wildcard Origin not allowed in credentials mode

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

# django-cors-headers configuration
CORS_ALLOWED_ORIGINS = ALLOWED_ORIGINS
CORS_ALLOW_CREDENTIALS = True

# Preflight (OPTIONS) requests do not include cookies!
# Do not require authentication on OPTIONS responses.
# → Exclude OPTIONS methods from your backend auth filters.

# Frontend: https://app.myservice.com
# Backend: https://api.myservice.com
# → Different Origins, so SameSite=Strict cookies are not sent
# → Use SameSite=None; Secure or the same parent domain

# localhost:3000 → localhost:8080 : Same site (cookies sent)
# localhost:3000 → 127.0.0.1:8080 : Different site! (cookies not sent)
# → Use the same hostname even in development

# Decoding JWT Payload (anyone can do this)
echo "eyJzdWIiOiJ1c2VyMTIzIn0" | base64 -d
# Output: {"sub":"user123"}

// Dangerous pattern
localStorage.setItem('token', jwt)

// Safe pattern: Use HttpOnly Cookie (set by server)
// Frontend does not handle tokens directly

# GET /api/users/delete?id=123  ← SameSite=Lax cannot defend against this!
# → State changes must always use POST/PUT/DELETE

# Works regardless of CORS
curl -X POST https://api.myservice.com/data \
  -H "Cookie: access_token=stolen_token"
# → Server-side token verification is essential

// Solution: Pattern to consolidate refresh requests into one
let refreshPromise = null

async function refreshToken() {
  if (refreshPromise) return refreshPromise // Wait if already refreshing

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

  return refreshPromise
}