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 데이터 입력

```sql
-- 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 인증을 일시적으로 비활성화하려면?

```sql
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 로그인에만 적용됩니다.