Authentication Flow와 OTP MFA

다른 이름: authentication flow · MFA · 2FA · OTP · TOTP · Configure OTP내용 검토: 2026. 09. 14.

결론부터

운영 중인 기본 flow를 직접 고치지 말고 복제본을 제한된 client에 적용해 비밀번호·OTP·복구 경로를 함께 검증한다.

로그인 정책은 한 화면의 옵션 하나가 아니라 순서와 조건을 가진 execution 묶음이다. 잘못 편집하면 모든 사용자와 관리자 로그인까지 막을 수 있으므로, 복제 flow와 전용 client에서 먼저 확인한다.

이 장에서 처음 나오는 말4개

authentication flow: 로그인 때 실행할 authenticator·조건·required action의 순서와 성공 규칙.
MFAMulti-Factor Authentication: 서로 다른 종류의 증명 수단을 둘 이상 요구하는 인증. 이 실습은 비밀번호와 TOTP를 쓴다.
TOTPTime-based One-Time Password: 공유 secret과 현재 시간 구간으로 짧은 일회용 숫자를 만드는 방식.
execution requirement: flow 단계가 Required·Alternative·Conditional·Disabled 중 어떻게 성공에 기여하는지 정하는 규칙.

큰 그림

사용자명·비밀번호 → Conditional 2FA → OTP 등록 여부 확인 → OTP Form → client callback 순서다. OTP가 아직 없으면 CONFIGURE_TOTP required action에서 먼저 등록한다. credential을 분실하면 관리자가 기존 OTP 하나를 삭제하고 required action을 다시 부여해 재등록 경로로 돌린다.

이 장에서 답할 질문

기본 flow를 직접 바꾸면 왜 위험한가?
비밀번호와 OTP 성공·실패를 어떻게 분리해 확인하는가?
OTP 기기를 잃어버린 사용자는 어떻게 복구시키는가?

복제본에서 시작한다

Keycloak 26.7 authentication flow 문서는 기존 flow를 복제해 수정하고 여러 모서리 조건을 시험하라고 권고한다. 이 실습은 기본 browser를 d09-browser-otp로 복제하지만 realm의 기본 binding은 바꾸지 않는다. 전용 public client d09-mfa의 browser flow override에만 연결한다.

확인 항목	실습 설정
첫 factor	Username Password Form, Required
두 번째 factor	Conditional 2FA 안의 OTP Form
최초 등록	전용 사용자에게 `CONFIGURE_TOTP` required action
client	Authorization Code + PKCE S256, 정확한 callback 하나
제외	implicit·password grant·service account

Conditional 2FA는 OTP credential이 이미 있는 사용자는 OTP Form으로 보내고, 없는 사용자는 그 조건만으로 자동 MFA가 되지 않는다. 모든 대상에게 OTP를 강제하려면 enrollment 정책과 복구 운영까지 함께 설계해야 한다.

등록과 로그인을 확인한다

기존 Compose 환경에서 D09 전용 seed와 검증을 실행한다.
터미널 창
```
cd labs/keycloak
./internal/verify/verify-d09.sh
```
첫 로그인에서 비밀번호를 통과한 뒤 Configure OTP 화면과 등록 완료 callback을 확인한다.
새 authentication session에서 틀린 OTP가 같은 form에서 거부되는지 확인한다.
정상 OTP가 client callback까지 도달하는지 확인한다.

검증 script는 Keycloak 26.7.3의 TOTP/HMAC-SHA1/6자리/30초 policy를 먼저 확인한다. OTP secret·code, password, cookie, authorization code는 process memory에만 두고 .state/verification/d09/에는 성공 조건만 기록한다.

분실 복구는 credential 교체다

사용자가 기기를 잃으면 기존 OTP를 알려 달라고 하지 않는다. 신원을 별도 절차로 확인한 관리자가 해당 사용자의 OTP credential만 삭제하고 CONFIGURE_TOTP를 다시 부여한다. 다음 password 로그인에서 새 secret을 등록하고, 최종 credential이 하나인지와 required action이 해제됐는지 확인한다.

복구 권한은 넓은 realm-admin 대신 필요한 사용자·credential 관리 권한으로 제한하고 모든 작업을 관리 이벤트에 남긴다. recovery code나 WebAuthn을 대체 factor로 쓰려면 동일하게 flow와 분실 시나리오를 별도로 검증해야 한다.

요약

기본 flow는 직접 고치지 않고 복제해 제한된 client에서 먼저 시험한다.
Conditional 2FA와 OTP enrollment required action은 함께 설계해야 한다.
성공만 보지 말고 오답 OTP 거부와 분실 후 credential 재등록까지 확인한다.
OTP 비밀값은 로그·검증 파일에 남기지 않고 관리 권한과 이벤트를 제한한다.