# staging Baron SSO 승인 로그인 검증 시나리오

작성일: 2026-07-06
상태: v0.2 진행 중

목적: `tdc114plus` 신규 전화번호 승인 로그인 흐름을 local Baron SSO runtime 대신 staging Baron SSO 환경에서 우선 검증하기 위한 절차를 정리한다. 공식 기준은 `Baron SSO Hosted Login + OIDC Authorization Code + PKCE`이며, headless 직접 호출은 레거시/참고 검증으로만 본다.

## 1. 왜 staging 경로를 우선 쓰는가

- 현재 local Baron SSO runtime에는 테스트 대상 전화번호의 identity/user mirror가 없을 수 있다.
- 이 경우 local에서는 `Hosted Login -> 문자/메일 링크 인증 -> App Link callback -> PKCE token 교환`을 끝까지 확인하기 어렵다.
- staging Baron SSO에 테스트 번호, RP 등록, redirect URI, 실제 링크 발송 경로가 준비되어 있다면 실제 승인 완료 end-to-end 검증을 더 빠르게 진행할 수 있다.

## 2. 적용 범위

이 시나리오는 아래 검증에 적용한다.

- staging Baron API smoke
- Android target 기준 staging API integration test
- 실제 승인 완료 로그인 1회 검증
- staging 반영 검토 전환 판단

## 3. 필요한 값

아래 값이 준비되어야 한다.

- `TDC114_API_BASE`
  - staging Baron API base URL
- `TDC114_SMOKE_PHONE`
  - staging Baron SSO에 등록된 테스트 전화번호
- 선택값 `TDC114_SMOKE_EXPECTED_NAME`
  - 로그인 후 화면에서 확인할 사용자명
- 선택값 `TDC114_SMOKE_EXPECTED_TENANT_LABEL`
  - 로그인 후 화면에서 확인할 조직 또는 테넌트 라벨

권장 env 파일:

```text
scripts/.env.staging.local
```

기본 예시는 아래 파일을 복사해서 사용한다.

```text
scripts/smoke.staging.env.example
```

## 4. 선행 조건

아래 조건이 먼저 만족되어야 한다.

- Flutter auth/model/widget test 통과
- backend handler/server test 통과
- staging 대상 Baron SSO Hosted Login, authorization endpoint, token endpoint가 사용 가능함
- 테스트 번호 수신 단말에서 링크 승인 가능
- 테스트 결과를 `docs/test-logs/2026-07-test-execution-log.md`에 기록할 준비가 되어 있음

배포 전 내부 준비 기준은 아래 순서를 따른다.

1. 로컬 구현 완료 고정
2. 자동화 테스트 고정
3. 로컬 API 계약 검증
4. Android target UI 기능 확인
5. Android target 실사용 흐름 점검
6. 수동 점검 체크리스트 정리
7. staging 반영 직전 검토

## 5. 권장 진행 순서

### 5.1 1단계: env 준비

예시:

```bash
cp scripts/smoke.staging.env.example scripts/.env.staging.local
```

값을 채운다.

```bash
TDC114_API_BASE=https://staging.example.com
TDC114_SMOKE_PHONE=010xxxxxxxx
TDC114_SMOKE_AUTH_FLOW=link
TDC114_SMOKE_EXPECTED_NAME=홍길동
TDC114_SMOKE_EXPECTED_TENANT_LABEL=IS3
```

사용자명과 조직 라벨은 optional이다. 값이 자주 바뀌거나 확실하지 않으면 비워둔다.

### 5.2 2단계: staging API smoke

먼저 host 기준 smoke를 확인한다.

```bash
TDC114_SMOKE_ENV_FILE=scripts/.env.staging.local ./scripts/api-smoke.sh
```

확인 포인트:

- Hosted Login authorization URL 생성 가능
- RP `client_id`, `redirect_uri`, PKCE `code_challenge` 조합이 Baron SSO에서 거부되지 않음
- App Link callback과 token 교환에 필요한 endpoint가 확인됨
- 레거시 headless smoke는 필요 시 참고로만 수행

주의:

- staging의 공식 성공 기준은 앱 직접 headless 호출이 아니라 Hosted Login 진입과 PKCE callback 완료다.
- 실제 승인 완료는 integration test 또는 수동 검증으로 이어서 확인한다.

### 5.3 3단계: Android target 준비

기존 Android runtime 절차를 따른다.

- emulator는 `docs/scenario_android_emulator_device_integration_test_2026-07-03.md`
- ADB 정책은 `docs/policy_android_studio_wsl_adb_2026-07-03.md`

핵심은 `TDC114_API_BASE`를 staging 값으로 바꾸고, 독립형 실기기 테스트에서는 `TDC114_SKIP_SESSION_BOOTSTRAP=true`로 로컬 legacy bootstrap을 끄는 것이다.

공기계 독립 실행 권장 env:

```text
scripts/.env.android-device.staging.local
```

예시:

```text
TDC114_API_BASE=https://staging.example.com
TDC114_SKIP_SESSION_BOOTSTRAP=true
TDC114_SMOKE_AUTH_FLOW=link
TDC114_SMOKE_PHONE=010xxxxxxxx
```

로그인만 staging, 직원/조직 데이터만 production으로 분리해야 하면 아래 override를 추가한다.

```text
TDC114_AUTH_API_BASE=https://staging.example.com
TDC114_DIRECTORY_API_BASE=https://production.example.com
TDC114_ORGANIZATION_API_BASE=https://production.example.com
```

### 5.4 4단계: staging integration test 실행

emulator fallback 예시:

```bash
TDC114_SMOKE_ENV_FILE=scripts/.env.staging.local \
TDC114_ADB_CONNECT_ADDRESS=172.21.128.1:5555 \
./scripts/integration_tests.sh
```

이미 승인된 prefix 경로를 쓰는 경우에는 기존 Android emulator 실행 방식과 동일하게 적용한다.

integration test의 현재 검증 기준:

- 로그인 화면 표시
- 빈 전화번호 validation
- `TDC114_SMOKE_PHONE`가 있으면 실제 번호 입력 후 로그인 시도
- 로그인 성공 시 `직원검색`, `검색 결과` 확인
- optional expected 값이 있으면 사용자명/조직 라벨까지 추가 확인

### 5.4-A 4-A단계: 공기계 독립 로그인 실행

공기계 또는 실사용 폰에 staging 직접 로그인 화면을 띄우려면 아래 경로를 사용한다.

```bash
ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.staging.local \
TDC114_FLUTTER_DEVICE_ID=<PHYSICAL_DEVICE_ID> \
./scripts/manual-postlogin-run.sh
```

이 모드에서는:

- 앱이 local legacy `phone-login` bootstrap을 시도하지 않는다.
- 앱이 staging Baron API를 직접 사용한다.
- 로그인은 앱의 `Baron SSO로 로그인` 버튼으로 Hosted Login을 열고, 인증 완료 후 App Link callback과 PKCE token 교환으로 완료한다.

### 5.5 5단계: 실제 승인 완료 수동 확인

테스트 단말에서 아래를 수행한다.

1. 앱에서 `Baron SSO로 로그인` 탭
2. 열린 Baron SSO Hosted Login 화면에서 휴대폰번호 입력
3. 수신된 문자 또는 메일의 링크 열기
4. `https://114.hmac.kr/auth/callback` App Link로 앱 복귀 확인
5. PKCE token 교환 후 `직원검색` 진입 확인

성공 기준:

- Baron SSO authorization endpoint 진입 성공
- 사용자가 수신 링크를 열 수 있음
- App Link callback 수신 및 `state` 검증 성공
- 앱 세션 저장 후 `직원검색` 화면 진입

## 5-A. staging 배포 전 수동 점검 체크리스트

아래 항목은 staging 반영 요청 전에 미리 채워두는 것을 권장한다.

### 5-A.1 에뮬레이터 기준 확인

- 로그인 화면이 정상 표시되는가
- 빈 전화번호 validation이 정상 동작하는가
- `Baron SSO로 로그인` 버튼이 Hosted Login 화면을 여는가
- 인증 대기 중 문구와 로딩 상태가 정상 표시되는가
- 오류 발생 시 내부 시스템 정보 없이 일반화된 안내 문구가 보이는가
- 로그인 성공 후 `직원검색` 첫 화면으로 진입하는가
- 첫 화면에서 기본 검색 결과가 표시되는가
- 직원 상세, 즐겨찾기, 전화/문자 버튼이 기존처럼 동작하는가

### 5-A.2 예외 시나리오 확인

- 미등록 번호 입력 시 generic 실패 안내가 보이는가
- 레거시 headless fallback을 켠 경우에만 만료된 `pendingRef`/poll 종료 처리가 자연스러운가
- poll 간격이 짧을 때 제한 응답 또는 재시도 대기 처리가 되는가
- 앱 재실행 후 세션 복원이 되는가
- 인증 만료 시 세션 정리 후 재로그인 흐름으로 복귀하는가

### 5-A.3 staging 반영 직전 확인

- 정확한 staging `TDC114_API_BASE`를 확보했는가
- 해당 base에서 Hosted Login authorization endpoint와 token endpoint를 사용할 수 있는가
- 테스트 번호로 문자 또는 메일 수신이 가능한가
- staging 로그 확인 담당자와 확인 위치를 알고 있는가
- 실패 시 되돌릴 범위와 회귀 확인 방법을 문서로 정리했는가

## 6. 예외 케이스 점검

실제 승인 완료 1회가 끝나면 아래를 추가 확인한다.

- 미등록 번호 입력 시 generic 실패 메시지
- 레거시 headless fallback을 켠 경우에만 만료된 `pendingRef` 처리
- polling 간격이 너무 짧을 때 `slow_down` 또는 유사 제한 동작
- 로그인 성공 후 directory API 401 없이 첫 화면 진입 가능한지

## 7. 성공 시 다음 판단

아래가 충족되면 staging 반영 검토 시작 가능 단계로 본다.

- 실제 승인 완료 end-to-end 1회 이상 통과
- 예외 케이스 점검 완료
- 테스트 번호, 로그 확인 포인트, 롤백 경로 정리

## 8. 현재 메모

- 2026-07-06 현재 local runtime에는 테스트 대상 전화번호 identity/user mirror가 없어 local 승인 완료 검증이 막혀 있다.
- 따라서 다음 실질 작업은 staging 번호와 staging API base를 확보해 위 절차로 1회 end-to-end를 끝까지 확인하는 것이다.

## 9. 팀장 공유용 문서 버전

이번 신규앱 로그인은 기존의 선인증 전화번호 로그인과 다르게, `전화번호 입력 -> 링크 발송 -> 사용자 승인 -> 승인 상태 polling -> 세션 저장`의 비동기 승인 절차를 거친다. 따라서 단순히 앱 소스 구현만 완료되었다고 해서 staging 반영 가능 상태라고 보기는 어렵고, staging Baron SSO 쪽에도 신규 로그인 흐름을 실제로 수용할 준비가 필요하다.

기존 로그인은 Baron SSO가 전화번호 확인 후 바로 세션을 발급하는 구조여서, 로컬 또는 기존 테스트 계정만으로도 비교적 빠르게 검증이 가능했다. 반면 이번 로그인은 사용자의 승인 링크 발송과 승인 완료 상태 변경이 중간에 개입하므로, staging 환경에서는 앱 코드 외에도 API 라우트 배포, 테스트 사용자 데이터, 링크 발송 경로, 승인 후 상태 조회가 모두 함께 맞아야 실제 end-to-end 검증이 가능하다.

따라서 이번 건은 "앱 구현 완료 후 즉시 staging 반영"이 아니라, "앱 구현과 backend 구현을 고정한 뒤 staging 준비 항목을 맞추고, 실제 승인 완료를 1회 이상 확인한 후 반영 검토" 순서로 접근하는 것이 안전하다.

## 10. staging 단계에서 준비가 필요한 항목

아래 항목은 로컬 준비가 아니라 staging 환경에서 선행되어야 하는 준비 사항이다.

### 10.1 staging 신규앱 API 배포 필요 여부

현재 기준으로는 필요 가능성이 매우 높다.

- 신규앱은 legacy 즉시 로그인이나 앱 직접 headless 호출보다 Baron SSO Hosted Login + PKCE 계약을 기본으로 사용한다.
- 따라서 staging 대상 Baron SSO/RP 설정에 아래 OIDC endpoint와 설정이 실제 사용 가능해야 한다.
  - Authorization endpoint
  - Token endpoint
  - TDC114PLUS RP `client_id`
  - `https://114.hmac.kr/auth/callback` redirect URI
- 추가로 로그인 이후 첫 화면 진입까지 확인하려면 아래 데이터 API도 확인되어야 한다.
  - `GET /api/v1/integrations/org-context`
  - 필요 시 `GET /api/v1/public/orgchart`

정리:

- staging에 TDC114PLUS RP 설정과 Hosted Login 흐름이 아직 반영되지 않았다면, 실제 승인 로그인 검증 전에 RP 등록/설정 반영이 선행되어야 한다.
- 단순 Baron SSO 대표 URL만 알고 있는 상태로는 부족하고, 실제 OIDC discovery/authorization/token endpoint와 redirect URI 허용 여부가 필요하다.

### 10.2 staging API base URL 확정

아래가 명확해야 한다.

- 신규앱이 호출해야 하는 정확한 staging `TDC114_API_BASE`
- 해당 base가 실제로 Swagger 공개 route를 제공하는지
- gateway, reverse proxy, auth middleware가 신규 route를 정상 통과시키는지

현재 확인상 `https://sso.hmac.kr`는 Baron SSO 대표 주소일 수는 있으나, 앱 데이터 API base로 확정할 근거는 부족했다.

### 10.3 staging 테스트 사용자 준비

staging Baron SSO에는 아래 조건을 만족하는 테스트 사용자가 준비되어야 한다.

- 테스트 전화번호가 staging Baron SSO 인증 대상 사용자로 존재
- 해당 사용자가 링크 발송 대상 lookup에서 조회 가능
- 승인 완료 후 앱 세션 발급 대상 사용자로 연결 가능
- 직원검색/조직도 API에서 앱 사용자로도 정상 조회 가능

쉽게 말하면 staging에서는 "전화번호를 아는 인증 사용자"와 "앱이 직원으로 인식하는 사용자 정보"가 둘 다 준비되어 있어야 한다.

### 10.4 staging 링크 발송 경로 준비

이번 로그인은 사용자가 실제 링크를 수신해야 하므로 아래가 staging에서 준비되어야 한다.

- 문자 또는 메일 발송 provider가 staging에서 활성화되어 있는지
- 테스트 번호에서 실제 링크를 수신 가능한지
- 링크 클릭 후 staging Baron SSO가 인증 완료 상태로 전환되고 redirect URI로 authorization code를 돌려주는지

이 항목이 안 맞으면 Hosted Login 진입은 성공해도 실제 승인 완료 검증은 끝까지 진행되지 않는다.

### 10.5 staging callback/token 교환 경로 준비

신규앱은 승인 후 App Link callback으로 authorization code를 받고, token endpoint에서 PKCE token 교환을 수행한다. 따라서 staging에서는 아래가 준비되어야 한다.

- `https://114.hmac.kr/auth/callback` redirect URI 허용
- callback에 `code`, `state` 전달
- token endpoint에서 `authorization_code + code_verifier` 교환 허용
- Client Secret 없이 PKCE 공개 앱으로 token 교환 가능

이 부분은 단순 route 존재 여부만으로는 부족하고, 실제 링크 승인과 callback/token 교환이 연결되어 있어야 한다.

### 10.6 staging 로그 확인 포인트 확보

실제 승인 로그인 검증 중에는 실패 원인 분리가 중요하므로 아래를 알아야 한다.

- staging backend 로그 확인 위치
- 필요 시 gateway 또는 auth 로그 확인 위치
- Hosted Login 진입, 링크 발송, callback redirect, token 교환 실패 로그를 누가 확인할 수 있는지

이 정보가 없으면 staging에서 실패가 나도 앱 문제인지, API 미배포인지, 사용자 데이터 문제인지 구분이 늦어진다.

### 10.7 staging 반영 실패 대비 경로

아래도 staging 단계에서 미리 정리되어야 한다.

- 신규앱 API가 미반영 상태로 남을 경우의 원복 또는 비활성 경로
- 기존 로그인 방식과 신규 로그인 방식의 분리 여부
- 문제가 생겼을 때 local 회귀 검증을 어떤 기준으로 다시 확인할지

이번 변경은 신규 로그인 플로우가 추가된 형태이므로, staging에서도 route 단위로 반영 범위와 되돌림 범위를 설명할 수 있어야 한다.

## 11. staging 준비 완료 판단 기준

아래가 충족되어야 staging에서 실제 승인 로그인 검증을 진행할 수 있다고 본다.

1. staging `TDC114_API_BASE`가 확정되었다.
2. staging Baron SSO에 TDC114PLUS RP와 Hosted Login + PKCE 설정이 반영되었다.
3. staging Baron SSO에 테스트 전화번호 사용자가 준비되었다.
4. 테스트 번호에서 실제 링크 수신이 가능하다.
5. 승인 후 App Link callback과 PKCE token 교환이 session 발급까지 이어진다.
6. 로그인 후 `직원검색` 첫 화면 진입이 가능하다.
7. 실패 시 확인할 로그 위치와 담당자 경로가 정리되었다.

위 기준이 충족되기 전에는 "staging 반영 가능"이라고 단정하지 않고, "staging 반영 검토 준비 단계"로 표현하는 것이 정확하다.
