Admin CMS MFA(2단계 인증) 설계 문서

개요

관리자 콘솔(admin) 로그인에 TOTP 기반 MFA를 추가한다. Cognito MFA 기능을 쓰지 않고 account-api 코드에서 직접 검증하며, 토큰 발급은 기존대로 Cognito를 사용한다.

작성일: 2026-10-01

현재 로그인 구조

Cognito는 토큰 발급기로만 쓰이고 인증 판단은 account-api 코드가 한다. MFA도 같은 자리(비번 검증 뒤, 토큰 발급 전)에 끼워 넣는다.

방식 선정

비교

비용

Cognito TOTP MFA 자체는 추가 요금 없음 (Lite/Essentials 모두 MAU 단가에 포함, SMS MFA만 SNS 비용). 관리자 Pool은 월 10,000 MAU 무료 구간 안이라 어느 방식이든 비용은 0원. 비용은 결정 요인 아님.

인증 앱

TOTP는 RFC 6238 표준이라 Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden 등 TOTP 지원 앱 모두 사용 가능.

시크릿 저장 위치

• TOTP 시드는 검증 시 원문이 필요해 단방향(해시) 저장 불가. 어떤 구현이든 복호화 가능한 형태로 보관 (Cognito도 동일)
• 관리자별 TOTP 시드 → admin_account.mfa_secret에 앱 레벨 암호화 후 저장
• 사용자별 시드를 Secrets Manager에 두는 것은 부적합 (시크릿당 월 과금, 로그인마다 API 호출, 사용자 데이터 이원화)
• 백업 코드만 단방향(bcrypt) 저장

시드 암호화 방식

MySQL AES_ENCRYPT를 쓰지 않는 이유: 키가 쿼리에 섞여 slow query 로그·binlog·에러 메시지에 남을 수 있음. Node에서 암호화하면 DB는 암호문만 다룸.

대안으로 KMS envelope 암호화 가능 (키 원문이 Lambda 메모리에도 없음, 자동 로테이션, 복호화마다 CloudTrail). 로그인마다 Decrypt 호출 1회. 현재 프로젝트들이 Secrets Manager만 쓰고 있어 1차는 Secrets Manager, 필요 시 v2: 접두어로 KMS 전환.

로그인 흐름

[admin 프론트]                 [account-api admin-account-api]              [DB admin_account]
    |                                   |                                        |
    |-- POST /login {account,pwd} ----->|                                        |
    |                                   |-- checkLogin (기존 그대로) ------------>|
    |                                   |<-- member (mfa_enabled 포함) -----------|
    |                                   |
    |      ┌─ mfa_enabled=0, MFA 강제 대상 아님  → 기존대로 Cognito 토큰 발급 (끝)
    |      ├─ mfa_enabled=0, MFA 강제 대상(내부관리자) → {step:"SETUP", mfaSession} 반환
    |      └─ mfa_enabled=1                        → {step:"VERIFY", mfaSession} 반환
    |<-- 200 {step, mfaSession} ---------|   (Authorization 헤더 없음, mfaSession은 5분 JWT)
    |
    |  [step = SETUP]
    |-- POST /mfa/setup {mfaSession} -->|  시드 생성 → 암호화 저장 (mfa_enabled 아직 0)
    |<-- {otpauthUri} ------------------|  프론트가 QR 렌더링
    |-- POST /mfa/confirm {mfaSession, code} -->|  코드 검증 성공 → mfa_enabled=1, 백업코드 발급
    |<-- Authorization 헤더 + {id,date,backupCodes} --|  이후 Cognito 토큰 발급
    |
    |  [step = VERIFY]
    |-- POST /mfa/verify {mfaSession, code} -->|  mfaSession 검증 → 시드 복호화 → TOTP 검증
    |                                   |      실패: mfa_fail_count+1, 10회 시 NonACTIVE
    |                                   |      성공: mfa_last_step 저장 → cognito.login(account, pwd)
    |<-- Authorization: id:access:refresh 헤더 + {id,date} --|  (현재 로그인 응답과 동일)

mfaSession

비번 검증은 통과했지만 OTP는 아직인 상태를 나타내는 임시 JWT.

DB 변경 (database-schema / account / admin_account)

서버 구조 (account-api / admin-account-api)

admin-account-api/
├── route.js                    /admin/mfa/setup, /mfa/confirm, /mfa/verify 추가
├── service/
│   ├── index.js                login(): checkLogin 이후, cognito.login 직전에 MFA 분기
│   └── mfa.js                  setup / confirm / verify / 공통 issueTokens()
├── repository/
│   └── adminAccount.js         findMfa, saveMfaSecret, enableMfa, updateMfaResult, resetMfa
├── utils/
│   ├── totp.js                 otplib 래퍼 (generateSecret, keyuri, verify + step 반환)
│   ├── mfaCrypto.js            AES-256-GCM encrypt / decrypt, Secrets Manager 키 캐시
│   └── mfaSession.js           sign / verify (5분 JWT)
└── static/account.js           AES_KEY (비번용, 기존 그대로. MFA에는 사용 안 함)

• 토큰 발급 코드는 issueTokens(member)로 분리해 login / confirm / verify 세 곳이 공유
• MFA 강제 대상 판단은 admin_type === 1 조건 한 곳. 제휴사 확대 시 이 조건만 변경
• 쿼리는 repository에만 작성 (database/rule.md 준수)
• TOTP 검증 window ±1 스텝(30초)

관리 기능 (admin-api)

프론트 구조 (admin / React)

src/
├── components/
│   ├── Login.jsx               응답 step 분기 (토큰 수신 시 기존대로, 아니면 MFA 화면)
│   ├── mfa/
│   │   ├── MfaSetup.jsx        QR(qrcode.react) + 첫 코드 입력 → /mfa/confirm → 백업코드 1회 표시
│   │   └── MfaVerify.jsx       6자리 입력 → /mfa/verify
│   └── admin/auth/...          관리자 상세에 "MFA 초기화" 버튼
├── routes/App.jsx              /admin/login/mfa 라우트 추가
└── redux/reducers/mfa.js       mfaSession, step 임시 보관 (persist 제외)

• 토큰 처리는 기존 Login.jsx와 동일하게 Authorization 헤더에서 추출
• AuthProtectedRoute.jsx 변경 없음 (mfaSession으로는 보호 라우트 진입 불가)

운영 정책

배포 순서

1. database-schema: admin_account 컬럼 추가 (기존 로그인 영향 없음)
2. account-api admin-account-api: MFA 엔드포인트 + login 분기 (mfa_enabled=0이면 기존 동작 유지)
3. admin-api: resetMfa, 목록/상세 mfa_enabled 노출
4. admin 프론트: MfaSetup / MfaVerify / 초기화 버튼
5. 내부관리자 강제 플래그 활성화

작업 분할

B·C·D는 독립적이라 컬럼명과 API 응답 형식만 확정하면 병렬 진행 가능.

향후 확장

• Passkey(WebAuthn): 코드 입력 대신 지문/Face ID로 기기 인증. 피싱 불가. 필요 시 @simplewebauthn/server로 TOTP와 병행 추가
• AES_KEY Secrets Manager 이관