eapim-admin/kjb-docs/sms-auth-guide.md

SMS 2차 인증 운영 가이드

개요

eLink Monitoring Admin 로그인 시 ID/PW 인증 후 SMS 인증번호를 통한 2차 인증을 수행합니다. SSO 로그인에는 적용되지 않습니다.

---

로그인 흐름

일반 로그인 (SMS 인증 활성화 시)

1. 로그인 페이지 접속
2. ID/PW 입력 → [Login] 버튼 클릭
3. SMS 인증 모달 표시 (등록된 휴대폰으로 인증번호 발송)
4. 인증번호 6자리 입력 → [확인] 버튼 클릭
5. 로그인 완료

SSO 로그인

1. 로그인 페이지 접속
2. [SSO Login] 버튼 클릭
3. SSO 인증 진행
4. 로그인 완료 (SMS 인증 없음)

---

설정 관리

설정 위치

모니터링 프로퍼티 (DB 테이블: TSEAIRM24, 그룹: Monitoring)

설정 항목

프로퍼티 키	기본값	설명
kjb.sms_auth.enabled	true	SMS 인증 사용 여부
kjb.sms_auth.mode	real	인증번호 생성 모드
kjb.sms_auth.fixed_value	654321	fixed 모드 시 사용할 고정 인증번호

인증번호 생성 모드 (kjb.sms_auth.mode)

모드	설명	용도
real	6자리 랜덤 숫자 생성	운영 환경
hhmm00	현재시각(HHmm) + "00" (예: 14:35 → 143500)	개발/테스트
fixed	kjb.sms_auth.fixed_value 값 사용	개발/테스트

---

비상 로그인

SSO 장애 또는 SMS 발송 장애 시 ID/PW만으로 로그인할 수 있는 비상 모드입니다.

사용 방법

https://{서버주소}/monitoring/loginForm.do?emergency

동작

• SSO 로그인 버튼 숨김
• SMS 2차 인증 우회
• ID/PW만으로 로그인 완료

주의사항

• 비상 상황에서만 사용
• 사용 시 서버 로그에 기록됨: 비상 로그인 모드 활성화 - SSO/SMS 인증 우회

---

SMS 인증 화면 안내

인증 모달

항목	설명
마스킹된 전화번호	010****1234 형식으로 표시
남은 시간	인증번호 유효시간 카운트다운 (60초)
재발송 버튼	20초 후 활성화, 남은 시간 표시 (예: 재발송 (15초))

인증 규칙

• 인증번호: 6자리 숫자
• 유효시간: 1분
• 재발송 가능: 발송 후 20초 경과 시

---

오류 상황 및 대응

1. "휴대폰번호가 등록되어 있지 않아 로그인할 수 없습니다"

원인: 사용자 정보에 휴대폰번호가 없음

대응:

• 관리자가 해당 사용자의 휴대폰번호 등록
• 또는 비상 로그인 사용 (/loginForm.do?emergency)

2. "인증번호 발송에 실패했습니다"

원인: UMS 서버 연동 오류

대응:

• UMS 서버 상태 확인
• 비상 로그인 사용 (/loginForm.do?emergency)
• 또는 SMS 인증 비활성화 (kjb.sms_auth.enabled = false)

3. "인증번호가 만료되었습니다"

원인: 1분 이내에 인증번호 입력하지 않음

대응:

• 모달 닫고 다시 로그인 시도
• 새 인증번호 발송됨

4. "인증번호가 일치하지 않습니다"

원인: 잘못된 인증번호 입력

대응:

• 정확한 6자리 숫자 입력
• 재발송 버튼으로 새 인증번호 요청 가능

---

로그 확인

로그 위치

서버 로그 파일 (Logback 설정에 따름)

주요 로그 메시지

로그	의미
SMS 인증번호 발송 완료 - guid: xxx, phone: 010****1234	인증번호 발송 성공
SMS 인증번호 검증 성공	인증 성공
SMS 인증번호 불일치	인증 실패 (잘못된 번호)
SMS 인증번호 만료됨	인증 실패 (시간 초과)
비상 로그인 모드 활성화 - SSO/SMS 인증 우회	비상 모드 접속

디버그 로그 (개발/테스트용)

-DLOGBACK_LOG_LEVEL=DEBUG 설정 시 인증번호가 로그에 출력됩니다:

SMS 인증번호 생성 (real 모드): 123456
SMS 인증번호 발송 - authCode: 123456

주의: 운영 환경에서는 DEBUG 로그 비활성화 권장

---

초기 설정 (신규 구축 시)

DB 데이터 입력

-- SMS 인증 설정 초기화
INSERT INTO EMSAPP.TSEAIRM24 (PRPTYGROUPNAME, PRPTYNAME, PRPTY2VAL)
VALUES ('Monitoring', 'kjb.sms_auth.enabled', 'true');

INSERT INTO EMSAPP.TSEAIRM24 (PRPTYGROUPNAME, PRPTYNAME, PRPTY2VAL)
VALUES ('Monitoring', 'kjb.sms_auth.mode', 'real');

INSERT INTO EMSAPP.TSEAIRM24 (PRPTYGROUPNAME, PRPTYNAME, PRPTY2VAL)
VALUES ('Monitoring', 'kjb.sms_auth.fixed_value', '654321');

UMS 연동 설정 확인

SMS 발송을 위해 UMS 관련 프로퍼티가 설정되어 있어야 합니다:

• kjb.ums.host_url
• kjb.ums.api_key
• 기타 UMS 연동 설정

---

FAQ

Q: SMS 인증을 일시적으로 비활성화하려면?

UPDATE EMSAPP.TSEAIRM24
SET PRPTY2VAL = 'false'
WHERE PRPTYGROUPNAME = 'Monitoring' AND PRPTYNAME = 'kjb.sms_auth.enabled';

Q: 특정 사용자만 SMS 인증을 우회하려면?

현재는 사용자별 설정이 없습니다.

• 해당 사용자에게 비상 로그인 URL 안내: /loginForm.do?emergency
• 또는 전체 SMS 인증 비활성화

Q: 인증번호를 미리 알 수 있나요? (테스트용)

kjb.sms_auth.mode 설정 변경:

• hhmm00: 현재시각 기반 (예: 14:35 → 143500)
• fixed: 고정값 사용 (kjb.sms_auth.fixed_value)

Q: SSO 로그인에도 SMS 인증이 적용되나요?

아니요. SMS 2차 인증은 ID/PW 로그인에만 적용됩니다.