KArtSell.Aegis/docs/JWT_PRODUCTION_DEPLOYMENT.md

JWT Production Deployment Guide

Phase 2: 프로덕션 배포 준비

배포 전 필수 작업

1️⃣ JWT 키 생성 (암호화 안전)

# 256비트 (32바이트) 안전한 랜덤 키 생성
# Option 1: PowerShell
$bytes = New-Object Byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$key = [Convert]::ToBase64String($bytes)
Write-Host "JWT_KEY=$key"

# Option 2: OpenSSL (WSL/Linux)
openssl rand -hex 32
# Output: 7e3f8c9a2b1d4e6f8a3c5b7d9e1f3a5c (convert to base64 if needed)

# Option 3: .NET CLI
dotnet user-secrets generate

결과 예시:

JWT_KEY=H4sIABST2GYC/0N+JxAkLxI9XxD8kWI5E9fC3x5mJ7dP8=

2️⃣ 데이터베이스 자격증명 검증 구현

현재 상태: 임시 테스트 구현 (모든 username/password 수용)

개선 사항: Database 기반 검증

Step 1: 마이그레이션 생성 (Credential 테이블)

-- Migration: 0045_identity_credentials.sql
BEGIN;

CREATE TABLE IF NOT EXISTS public.identity_credential (
  credential_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  
  -- Reference to identity
  identity_id UUID NOT NULL UNIQUE REFERENCES public.identity(identity_id) ON DELETE CASCADE,
  
  -- Password storage (bcrypt hash)
  password_hash VARCHAR(255) NOT NULL,
  
  -- Credential state
  state VARCHAR(50) NOT NULL DEFAULT 'ACTIVE'
    CHECK (state IN ('ACTIVE', 'SUSPENDED', 'EXPIRED', 'REVOKED')),
  
  -- Failed login tracking
  failed_attempts INT DEFAULT 0,
  locked_until TIMESTAMP WITH TIME ZONE,
  
  -- Lifecycle
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  
  -- Idempotency
  correlation_id UUID UNIQUE
);

CREATE INDEX idx_identity_credential_identity ON public.identity_credential(identity_id);
CREATE INDEX idx_identity_credential_state ON public.identity_credential(state);

COMMIT;

Step 2: LoginEndpoint 수정

public override async Task HandleAsync(LoginRequest req, CancellationToken ct)
{
  logger.LogInformation("Login attempt for user: {User}", req.Username);

  if (string.IsNullOrWhiteSpace(req.Username) || string.IsNullOrWhiteSpace(req.Password))
  {
    logger.LogWarning("Login failed: missing credentials");
    ThrowError(x => x.AddError("credentials", "Username and password required"));
  }

  // FUTURE: Query database for identity by username
  // var identity = await sql.GetIdentityByUsernameAsync(req.Username, ct);
  
  // FUTURE: Get credential record
  // var credential = await sql.GetCredentialAsync(identity.Id, ct);
  
  // FUTURE: Verify password
  // if (!BCrypt.Net.BCrypt.Verify(req.Password, credential.PasswordHash))
  // {
  //   await sql.RecordFailedLoginAttemptAsync(credential.Id, ct);
  //   ThrowError(x => x.AddError("credentials", "Invalid credentials"));
  // }
  
  // TEMPORARY: Accept any non-empty credentials
  var token = GenerateJwtToken(req.Username, req.Role ?? "User");
  logger.LogInformation("Token issued for user: {User}", req.Username);

  // ... rest of implementation
}

3️⃣ 환경 변수 설정 (배포 시)

Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: kartsell-jwt
type: Opaque
data:
  JWT_KEY: SGg0c0lBQlNUM...  # Base64 encoded

Docker/.env:

JWT_KEY=H4sIABST2GYC/0N+JxAkLxI9XxD8kWI5E9fC3x5mJ7dP8=
KARTSELL_POSTGRES=Host=db.production.internal;Port=5432;Database=kartselldb;Username=kartsell;Password=...

AWS Systems Manager:

aws ssm put-parameter \
  --name /kartsell/jwt/key \
  --value "H4sIABST2GYC/0N+JxAkLxI9XxD8kWI5E9fC3x5mJ7dP8=" \
  --type "SecureString"

4️⃣ appsettings 배포 설정

appsettings.Release.json 검증:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:5002"
      }
    }
  },
  "Authentication": {
    "Mode": "JWT"
  },
  "Jwt": {
    "Key": "${JWT_KEY}",  // ✅ Environment variable
    "Issuer": "KArtSell.Aegis",
    "Audience": "KArtSell.Aegis",
    "ExpirationMinutes": 60
  },
  "ConnectionStrings": {
    "Postgres": "${KARTSELL_POSTGRES}"  // ✅ Environment variable
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information"
    }
  }
}

5️⃣ HTTPS/TLS 설정

Kestrel HTTPS:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://0.0.0.0:443",
        "Certificate": {
          "Path": "/etc/ssl/certs/kartsell.pfx",
          "Password": "${CERT_PASSWORD}"
        }
      }
    }
  }
}

Nginx Reverse Proxy:

upstream backend {
    server kartsell-host:5002;
}

server {
    listen 443 ssl http2;
    server_name api.kartsell.taxbaik.com;
    
    ssl_certificate /etc/nginx/ssl/kartsell.crt;
    ssl_certificate_key /etc/nginx/ssl/kartsell.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    location /api/auth/login {
        proxy_pass http://backend;
        proxy_set_header Authorization "";  # Don't forward client auth
    }
    
    location /api {
        proxy_pass http://backend;
        proxy_set_header Authorization $http_authorization;
        proxy_pass_header Authorization;
    }
}

배포 체크리스트

보안

• JWT_KEY 환경변수 설정 (256+ bits, cryptographically secure)
• HTTPS only (HTTP → HTTPS redirect)
• TLS 1.2+ enforced
• HSTS header enabled (Strict-Transport-Security)
• CORS properly configured (whitelist specific origins)
• Rate limiting on /api/auth/login (max 5 attempts/min per IP)
• Database credentials in secret manager (not hardcoded)
• JWT key rotation schedule planned (annual minimum)

성능

• Connection pooling configured (min 10, max 50)
• Caching enabled for authentication checks
• Load balancer session affinity configured
• CDN configured for static assets
• Database query optimization verified

모니터링

• Authentication success/failure metrics logged
• Failed login attempts alerting (>10/min = alert)
• JWT validation errors tracked
• Token expiration events logged
• Authorization failures monitored

데이터베이스

• Backup schedule configured (daily minimum)
• Password hashing algorithm decided (bcrypt/argon2)
• Credential table indexed for fast lookups
• Audit logging enabled
• Database connection encryption (SSL)

배포

• Database migrations pre-validated
• Rollback plan documented
• Canary deployment configured (5% → 25% → 100%)
• Health checks configured (/health/ready endpoint)
• Log aggregation configured (ELK/Datadog)

배포 절차

단계 1: 프로덕션 환경 준비

# 1. 환경 변수 설정
export JWT_KEY="H4sIABST2GYC/0N+JxAkLxI9XxD8kWI5E9fC3x5mJ7dP8="
export KARTSELL_POSTGRES="Host=prod-db;Port=5432;Database=kartselldb;Username=kartsell;Password=..."

# 2. 데이터베이스 마이그레이션 실행
dotnet KArtSell.DbMigrator.dll

# 3. 헬스 체크
curl https://api.kartsell.taxbaik.com/health/ready
# Expected: 200 OK

단계 2: 배포 (Blue-Green)

# Blue: 현재 운영 환경 (v1.0)
# Green: 새 배포 환경 (v2.0)

# 1. Green 환경에 v2.0 배포
docker run -d \
  -e JWT_KEY=$JWT_KEY \
  -e KARTSELL_POSTGRES=$KARTSELL_POSTGRES \
  -p 5002:5002 \
  kartsell:v2.0

# 2. Green 환경 헬스 체크
curl http://localhost:5002/health/ready

# 3. Green 환경 테스트
# - Login flow
# - API requests with JWT
# - Token expiration

# 4. 로드 밸런서 Green으로 전환
# Blue → Green traffic switch

# 5. Blue 환경 모니터링 (rollback 준비)
# 30분 동안 이상 없으면 Blue 종료

단계 3: 배포 후 검증

# 1. JWT 토큰 발급 테스트
curl -X POST https://api.kartsell.taxbaik.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test","role":"Admin"}'

# Expected response:
# {
#   "accessToken": "eyJhbGc...",
#   "expiresIn": 3600,
#   "tokenType": "Bearer"
# }

# 2. API 엔드포인트 인증 테스트
TOKEN="eyJhbGc..."
curl https://api.kartsell.taxbaik.com/api/identities \
  -H "Authorization: Bearer $TOKEN"

# Expected: 200 OK (또는 관련 비즈니스 응답)

# 3. 모니터링 대시보드 확인
# - Authentication success rate
# - API latency
# - Error rates

# 4. 로그 확인
# - 비정상적인 인증 실패 없음
# - 토큰 검증 오류 없음

롤백 절차

토큰 생성/검증 오류 발생 시:

# 1. 즉시 Blue 환경으로 복구
# 로드 밸런서 Blue로 전환

# 2. 문제 분석
# - JWT_KEY 환경변수 확인
# - 데이터베이스 연결 확인
# - 로그 분석

# 3. 문제 수정 후 재배포

모니터링 쿼리

인증 성공률

SELECT 
  DATE_TRUNC('hour', created_at) as hour,
  COUNT(*) FILTER (WHERE status = 'success') as success_count,
  COUNT(*) FILTER (WHERE status = 'failure') as failure_count,
  ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'success') / COUNT(*), 2) as success_rate
FROM auth_logs
WHERE created_at > NOW() - INTERVAL '24 hours'
GROUP BY DATE_TRUNC('hour', created_at)
ORDER BY hour DESC;

토큰 검증 오류

SELECT error_message, COUNT(*) as count
FROM jwt_validation_errors
WHERE created_at > NOW() - INTERVAL '1 hour'
GROUP BY error_message
ORDER BY count DESC;

성공 기준

배포 후 최소 24시간 모니터링:

• Authentication success rate > 99%
• API latency < 200ms (p95)
• Token validation errors = 0
• Failed login attempts < 5/minute average
• No database connection errors
• User reports = 0

이 모든 기준을 충족하면 배포 완료! ✅