SSO 통합 실전 가이드 — OIDC/OAuth2 + 쿠키/JWT 하이브리드 아키텍처, 토큰 로테이션 완전 정복

[사용자] ──로그인──▶ [IdP (Identity Provider)]
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
    [앱 A]            [앱 B]            [앱 C]
   (이메일)          (위키)          (CI/CD)
   재로그인 불필요   재로그인 불필요   재로그인 불필요

OAuth 2.0 = "이 앱이 네 Google Drive를 읽어도 돼?" (인가)
OIDC      = "로그인한 사람이 youngjukim@example.com이야" (인증) + OAuth 2.0

┌──────────┐                           ┌──────────┐                    ┌──────────┐
│ Browser  │                           │   BFF    │                    │   IdP    │
│ (User)   │                           │ (Server) │                    │(Keycloak)│
└────┬─────┘                           └────┬─────┘                    └────┬─────┘
     │  1. /login 클릭                      │                               │
     │─────────────────────────────────────▶│                               │
     │                                      │  2. code_verifier 생성        │
     │                                      │     code_challenge =          │
     │                                      │     SHA256(code_verifier)     │
     │  3. 302 Redirect to IdP             │                               │
     │◀─────────────────────────────────────│                               │
     │  (/authorize?response_type=code      │                               │
     │   &client_id=...                     │                               │
     │   &code_challenge=...                │                               │
     │   &code_challenge_method=S256)       │                               │
     │──────────────────────────────────────────────────────────────────────▶│
     │                                      │     4. 사용자 로그인 + 동의    │
     │◀──────────────────────────────────────────────────────────────────────│
     │  5. redirect_uri?code=AUTH_CODE      │                               │
     │─────────────────────────────────────▶│                               │
     │                                      │  6. POST /token               │
     │                                      │     code + code_verifier      │
     │                                      │─────────────────────────────▶│
     │                                      │  7. AT + RT + ID Token        │
     │                                      │◀─────────────────────────────│
     │  8. Set-Cookie: session_id           │                               │
     │◀─────────────────────────────────────│                               │

# Python: PKCE code_verifier / code_challenge 생성
import secrets
import hashlib
import base64

# 1. code_verifier: 43~128자 랜덤 문자열
code_verifier = secrets.token_urlsafe(64)[:128]

# 2. code_challenge: SHA256 해시 후 Base64url 인코딩
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode()).digest()
).rstrip(b'=').decode()

print(f"code_verifier:  {code_verifier}")
print(f"code_challenge: {code_challenge}")

{
  "iss": "https://idp.example.com",
  "sub": "user-uuid-1234",
  "aud": "my-client-id",
  "exp": 1709913600,
  "iat": 1709910000,
  "nonce": "abc123xyz",
  "email": "youngjukim@example.com",
  "name": "김영주",
  "email_verified": true
}

scope: "openid profile email read:calendar write:calendar"

┌─────────────────────────────────────────────────────┐
│                      Browser                         │
│  세션 쿠키만 보유 (HttpOnly, Secure, SameSite=Lax)   │
│  JavaScript에서 토큰 접근 불가 → XSS로부터 안전      │
└──────────────────────┬──────────────────────────────┘
                       │ Cookie: session_id=xxx
                       ▼
┌──────────────────────────────────────────────────────┐
│                  BFF (Backend For Frontend)           │
│  ┌──────────────────────────────────────────────┐    │
│  │ 세션 저장소 (Redis)                           │    │
│  │  session_id → { access_token, refresh_token,  │    │
│  │                  id_token, user_info }         │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────┬──────────────────────────────┘
                       │ Authorization: Bearer <JWT>
                       ▼
┌──────────────────────────────────────────────────────┐
│              Backend Microservices                    │
│   [User API]  [Order API]  [Payment API]  [...]      │
└──────────────────────────────────────────────────────┘

# Spring Cloud Gateway - Token Relay 설정
spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - TokenRelay= # 자동으로 Access Token을 Authorization 헤더에 추가
            - RemoveRequestHeader=Cookie # 쿠키는 백엔드로 전달하지 않음

// application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: my-app
            client-secret: ${KEYCLOAK_SECRET}
            scope: openid, profile, email
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          keycloak:
            issuer-uri: https://keycloak.example.com/realms/my-realm

// SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .defaultSuccessUrl("/dashboard")
            )
            .oauth2Client(Customizer.withDefaults());
        return http.build();
    }
}

# settings.py
INSTALLED_APPS += ['mozilla_django_oidc']

AUTHENTICATION_BACKENDS = [
    'mozilla_django_oidc.auth.OIDCAuthenticationBackend',
    'django.contrib.auth.backends.ModelBackend',
]

OIDC_RP_CLIENT_ID = os.environ['OIDC_CLIENT_ID']
OIDC_RP_CLIENT_SECRET = os.environ['OIDC_CLIENT_SECRET']
OIDC_OP_AUTHORIZATION_ENDPOINT = 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth'
OIDC_OP_TOKEN_ENDPOINT = 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token'
OIDC_OP_USER_ENDPOINT = 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/userinfo'
OIDC_OP_JWKS_ENDPOINT = 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/certs'
OIDC_RP_SIGN_ALGO = 'RS256'

# urls.py
urlpatterns += [
    path('oidc/', include('mozilla_django_oidc.urls')),
]

// app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth'
import KeycloakProvider from 'next-auth/providers/keycloak'

const handler = NextAuth({
  providers: [
    KeycloakProvider({
      clientId: process.env.KEYCLOAK_CLIENT_ID!,
      clientSecret: process.env.KEYCLOAK_CLIENT_SECRET!,
      issuer: process.env.KEYCLOAK_ISSUER, // https://keycloak.example.com/realms/my-realm
    }),
  ],
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token
        token.refreshToken = account.refresh_token
        token.expiresAt = account.expires_at
      }
      // 만료 전 갱신
      if (Date.now() < (token.expiresAt as number) * 1000) {
        return token
      }
      return refreshAccessToken(token)
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken as string
      return session
    },
  },
})

export { handler as GET, handler as POST }

Google:    https://accounts.google.com/.well-known/openid-configuration
Azure AD:  https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
Okta:      https://{domain}.okta.com/.well-known/openid-configuration
Keycloak:  https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration

// 범용 OIDC Discovery 활용 (Node.js)
import { Issuer } from 'openid-client'

async function setupOIDC(issuerUrl: string, clientId: string, clientSecret: string) {
  const issuer = await Issuer.discover(issuerUrl)

  console.log('Authorization Endpoint:', issuer.metadata.authorization_endpoint)
  console.log('Token Endpoint:', issuer.metadata.token_endpoint)
  console.log('UserInfo Endpoint:', issuer.metadata.userinfo_endpoint)
  console.log('JWKS URI:', issuer.metadata.jwks_uri)

  const client = new issuer.Client({
    client_id: clientId,
    client_secret: clientSecret,
    redirect_uris: ['https://myapp.example.com/callback'],
    response_types: ['code'],
  })

  return client
}

[정상 흐름]
Client → POST /token (grant_type=refresh_token, refresh_token=RT_1)
Server → 새 AT_2 + 새 RT_2 발급, RT_1 무효화

[탈취 시나리오 — Automatic Reuse Detection]
공격자가 RT_1을 탈취 후 사용:
  공격자 → POST /token (refresh_token=RT_1)  ← 이미 사용된 RT!
  Server → RT_1이 이미 사용됨을 감지
         → RT_1의 전체 토큰 패밀리(RT_2, RT_3 ...) 모두 무효화
         → 사용자 강제 재로그인

// Node.js / Express: Refresh Token Rotation 구현
import { randomUUID } from 'crypto'
import Redis from 'ioredis'

const redis = new Redis()

interface TokenFamily {
  userId: string
  familyId: string
  usedTokens: Set<string>
}

async function rotateRefreshToken(currentRefreshToken: string) {
  const tokenData = await redis.get(`rt:${currentRefreshToken}`)
  if (!tokenData) {
    throw new Error('INVALID_REFRESH_TOKEN')
  }

  const parsed = JSON.parse(tokenData)
  const familyKey = `family:${parsed.familyId}`

  // Reuse Detection: 이미 사용된 토큰이면 전체 패밀리 무효화
  const isUsed = await redis.sismember(`${familyKey}:used`, currentRefreshToken)
  if (isUsed) {
    console.warn(`[SECURITY] Token reuse detected! Family: ${parsed.familyId}`)
    await revokeTokenFamily(parsed.familyId)
    throw new Error('TOKEN_REUSE_DETECTED')
  }

  // 현재 RT를 "사용됨"으로 표시
  await redis.sadd(`${familyKey}:used`, currentRefreshToken)

  // 새 토큰 발급
  const newRefreshToken = randomUUID()
  const newAccessToken = generateJWT(parsed.userId)

  await redis.setex(
    `rt:${newRefreshToken}`,
    7 * 24 * 3600,
    JSON.stringify({
      userId: parsed.userId,
      familyId: parsed.familyId,
      createdAt: Date.now(),
    })
  )

  // 기존 RT 삭제
  await redis.del(`rt:${currentRefreshToken}`)

  return { accessToken: newAccessToken, refreshToken: newRefreshToken }
}

async function revokeTokenFamily(familyId: string) {
  const members = await redis.smembers(`family:${familyId}:used`)
  const pipeline = redis.pipeline()
  for (const token of members) {
    pipeline.del(`rt:${token}`)
  }
  pipeline.del(`family:${familyId}:used`)
  await pipeline.exec()
}

// Axios 인터셉터: Hybrid 갱신 전략
import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios'

let isRefreshing = false
let failedQueue: Array<{ resolve: Function; reject: Function }> = []

const api = axios.create({ baseURL: '/api', withCredentials: true })

api.interceptors.response.use(
  (response) => response,
  async (error: AxiosError) => {
    const originalRequest = error.config as InternalAxiosRequestConfig & { _retry?: boolean }

    if (error.response?.status === 401 && !originalRequest._retry) {
      if (isRefreshing) {
        // 이미 갱신 중이면 큐에 추가
        return new Promise((resolve, reject) => {
          failedQueue.push({ resolve, reject })
        }).then(() => api(originalRequest))
      }

      originalRequest._retry = true
      isRefreshing = true

      try {
        await axios.post('/api/auth/refresh', {}, { withCredentials: true })
        failedQueue.forEach(({ resolve }) => resolve())
        failedQueue = []
        return api(originalRequest)
      } catch (refreshError) {
        failedQueue.forEach(({ reject }) => reject(refreshError))
        failedQueue = []
        window.location.href = '/login'
        return Promise.reject(refreshError)
      } finally {
        isRefreshing = false
      }
    }
    return Promise.reject(error)
  }
)

// Express.js: 세션 쿠키 설정 (BFF)
import session from 'express-session'
import RedisStore from 'connect-redis'
import { createClient } from 'redis'

const redisClient = createClient({ url: process.env.REDIS_URL })
await redisClient.connect()

app.use(
  session({
    store: new RedisStore({ client: redisClient }),
    name: '__Host-session', // __Host- 접두사: Secure + 특정 도메인에 고정
    secret: process.env.SESSION_SECRET!,
    resave: false,
    saveUninitialized: false,
    cookie: {
      httpOnly: true, // JavaScript 접근 불가
      secure: true, // HTTPS만 전송
      sameSite: 'lax', // CSRF 방어: 외부 사이트에서 전송 차단
      maxAge: 24 * 60 * 60 * 1000, // 24시간
      path: '/',
      // domain 생략 → 현재 호스트에만 적용 (__Host- 접두사와 함께)
    },
  })
)

// Set-Cookie 헤더 결과 예시:
// Set-Cookie: __Host-session=s%3Aabc123...; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=86400

# Domain 속성을 이용한 서브도메인 쿠키 공유
Set-Cookie: session=abc; Domain=.example.com; Path=/; HttpOnly; Secure; SameSite=Lax

→ app1.example.com, app2.example.com, admin.example.com 모두에서 쿠키 전송

// 프론트엔드: credentials: 'include' 설정 필수
fetch('https://api.example.com/data', {
  method: 'GET',
  credentials: 'include', // 쿠키를 cross-origin으로 전송
})

// 백엔드: CORS 설정 (Express)
app.use(
  cors({
    origin: 'https://app.example.com', // '*' 사용 불가 (credentials 사용 시)
    credentials: true, // Access-Control-Allow-Credentials: true
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization', 'X-CSRF-Token'],
  })
)

// Express: 로컬 로그아웃 (세션 + 쿠키 삭제)
app.post('/logout', async (req, res) => {
  const sessionData = req.session

  // 1. IdP의 토큰을 revoke (선택적이지만 권장)
  if (sessionData?.refreshToken) {
    await fetch(`${ISSUER}/protocol/openid-connect/revoke`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        token: sessionData.refreshToken,
        token_type_hint: 'refresh_token',
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
      }),
    })
  }

  // 2. 세션 삭제
  req.session.destroy((err) => {
    if (err) console.error('Session destroy error:', err)
    // 3. 쿠키 삭제
    res.clearCookie('__Host-session', { path: '/', httpOnly: true, secure: true })
    res.json({ success: true })
  })
})

// 사용자를 IdP의 로그아웃 페이지로 리다이렉트
const logoutUrl = new URL(`${ISSUER}/protocol/openid-connect/logout`)
logoutUrl.searchParams.set('id_token_hint', idToken)
logoutUrl.searchParams.set('post_logout_redirect_uri', 'https://app.example.com')
res.redirect(logoutUrl.toString())

// POST /backchannel-logout 엔드포인트 (각 서비스에 구현)
app.post('/backchannel-logout', async (req, res) => {
  const { logout_token } = req.body

  // logout_token (JWT) 검증
  const decoded = await verifyLogoutToken(logout_token)
  const userId = decoded.sub
  const sessionId = decoded.sid

  // 해당 사용자의 모든 세션 무효화
  await redis.del(`user_sessions:${userId}`)
  console.log(`[Back-Channel Logout] User ${userId} session ${sessionId} invalidated`)

  res.sendStatus(200)
})

<!-- IdP가 렌더링하는 로그아웃 페이지에 각 RP의 로그아웃 iframe 삽입 -->
<iframe src="https://app1.example.com/logout?sid=xxx" width="0" height="0"></iframe>
<iframe src="https://app2.example.com/logout?sid=xxx" width="0" height="0"></iframe>

// JWT 블랙리스트 미들웨어
async function jwtBlacklistMiddleware(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace('Bearer ', '')
  if (!token) return res.sendStatus(401)

  // 블랙리스트 확인 (jti 또는 토큰 해시)
  const decoded = jwt.decode(token) as { jti: string; exp: number }
  const isBlacklisted = await redis.exists(`blacklist:${decoded.jti}`)

  if (isBlacklisted) {
    return res.status(401).json({ error: 'Token has been revoked' })
  }

  // 정상 JWT 검증
  try {
    req.user = jwt.verify(token, PUBLIC_KEY, { algorithms: ['RS256'] })
    next()
  } catch {
    return res.sendStatus(401)
  }
}

// 블랙리스트 등록 (로그아웃 또는 관리자 강제 무효화)
async function revokeToken(token: string) {
  const decoded = jwt.decode(token) as { jti: string; exp: number }
  const ttl = decoded.exp - Math.floor(Date.now() / 1000)
  if (ttl > 0) {
    await redis.setex(`blacklist:${decoded.jti}`, ttl, '1')
  }
}

POST /token/introspect HTTP/1.1
Host: idp.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=abc123opaque_token

→ 응답:
{
  "active": true,
  "sub": "user-1234",
  "scope": "openid profile",
  "client_id": "my-app",
  "exp": 1709913600
}

# Kong Gateway: JWT 검증 플러그인 설정
plugins:
  - name: jwt
    config:
      uri_param_names: []
      header_names: ['Authorization']
      claims_to_verify:
        - exp
      key_claim_name: iss
      secret_is_base64: false

// Go: API Gateway JWT 검증 미들웨어
func JWTMiddleware(jwksURL string) func(http.Handler) http.Handler {
    keySet, _ := jwk.Fetch(context.Background(), jwksURL)

    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            tokenStr := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
            token, err := jwt.Parse([]byte(tokenStr), jwt.WithKeySet(keySet),
                jwt.WithValidate(true),
                jwt.WithAudience("my-api"),
            )
            if err != nil {
                http.Error(w, "Unauthorized", http.StatusUnauthorized)
                return
            }
            ctx := context.WithValue(r.Context(), "user", token)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

사용자 → BFF:         aud=["bff-service"]
BFF → User Service:   aud=["user-service"]     (토큰 교환 또는 새 토큰 발급)
BFF → Order Service:  aud=["order-service"]

# Istio: RequestAuthentication + AuthorizationPolicy
apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: jwt-auth
spec:
  jwtRules:
    - issuer: 'https://idp.example.com'
      jwksUri: 'https://idp.example.com/.well-known/jwks.json'
      forwardOriginalToken: true
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: require-jwt
spec:
  rules:
    - from:
        - source:
            requestPrincipals: ['*']
      when:
        - key: request.auth.claims[aud]
          values: ['order-service']