비밀번호 재설정 운영 가이드
사용자가 비밀번호 재설정 을 요청했을 때 내부적으로 동작하는 흐름과 운영자 조치 절차.
동작 흐름
로그인 페이지
"비밀번호를 잊으셨나요?" 클릭
↓
이메일 입력 → Keycloak에 reset credentials 요청
↓
Keycloak SMTP → 사용자 메일함 (Update Password 링크)
↓
사용자 클릭 → Keycloak 재설정 페이지
↓
새 비밀번호 저장 → 기존 세션 일괄 종료
전제 조건
SMTP 설정 필수 — 메일 발송이 안 되면 사용자는 재설정 링크를 받지 못합니다.
- Keycloak Realm → Email 탭에서 SMTP 서버 설정
- Host / Port / From / Reply-To
- Authentication 계정
- TLS/StartTLS 여부
- 방화벽/NAT에서 SMTP Gateway 아웃바운드 허용
- Admin Console → Realm Settings → Login → Forgot Password ON
비밀번호 정책 설정
Realm Settings → Authentication → Password Policies 에서 구성:
| 정책 | 권장값 | 설명 |
|---|
| Minimum Length | 10+ | 최소 길이 |
| Digits | 1 | 숫자 최소 개수 |
| Uppercase | 1 | 대문자 최소 개수 |
| Special Characters | 1 | 특수문자 최소 개수 |
| Not Recently Used | 5 | 최근 N개 재사용 금지 |
| Password Expire | 90 days | 비밀번호 만료 주기 |
| Hashing Iterations | 27500+ | 해시 반복 (PBKDF2 기본) |
운영자 수동 조치
사용자가 이메일을 받지 못하거나 긴급 상황일 때:
강제 비밀번호 재설정 (관리자)
대상 사용자 선택
Keycloak Admin Console → Users → 검색 → 사용자 선택.
Credentials 탭
Reset Password 버튼 또는 직접 Set Password.
임시 비밀번호 설정
Temporary: ON 로 설정하면 사용자가 다음 로그인 시 변경을 강제받음. 안전한 채널로 임시 값 전달.
(대안) Reset Actions 보내기
Credential Reset → Update Password 액션 선택 → Send email.
메일이 정상 전송되면 사용자가 스스로 변경.
로그·감사
- Events → Login Events 에서
RESET_PASSWORD, UPDATE_PASSWORD 이벤트 확인
- 이벤트 보존 설정: Realm Settings → Events (기본 365일)
- 실패 이벤트만 저장하고 있으면 성공도 기록하도록 Save Events ON
관련 문서
