# 신규앱과 Baron SSO 연동 쉬운 설명

작성일: 2026-07-08
상태: 초안 v1

목적: 신규앱과 Baron SSO의 관계, 데이터 연동 방식, headless 로그인, 모바일 배포 형태를 다른 팀원도 쉽게 이해할 수 있게 설명한다.

관련 근거:

- `docs/00_contract_tdc114plus_api_2026-07-02.md`
- `docs/00_policy_tdc114plus_screen_feature_2026-07-07.md`
- `docs/scenario_staging_baron_sso_login_verification_2026-07-06.md`
- `docs/policy_android_app_install_execution_2026-07-06.md`
- `app/lib/src/features/auth/data/auth_api_client.dart`
- `app/lib/src/features/auth/domain/auth_models.dart`
- `app/lib/src/features/auth/data/auth_repository.dart`

## 1. 한 줄 요약

`tdc114plus` 신규앱은 Baron SSO 자체가 아니라, Baron SSO를 로그인/사용자정보/조직정보 제공자로 사용하는 별도의 모바일 앱이다.

쉽게 말하면:

- 신규앱 = 사용자가 설치해서 실행하는 앱
- Baron SSO = 로그인과 사용자/조직 데이터를 제공하는 서버
- 두 시스템은 API로 데이터를 주고받는다

## 2. 신규앱과 Baron SSO의 관계

### 2.1 무엇이 누구인가

- 신규앱은 Flutter로 만든 Android/iOS 공통 모바일 앱이다.
- Baron SSO는 사용자 인증과 조직/직원 데이터를 관리하는 서버 쪽 시스템이다.
- 신규앱은 Baron SSO에 등록되는 별도 `RP(Relying Party)`로 본다.

여기서 `RP`는 쉽게 말하면:

- "SSO를 믿고 로그인 기능을 맡기는 서비스"
- 즉, 로그인 자체를 새로 만들지 않고 Baron SSO를 통해 인증받는 앱

그래서 신규앱은 Baron SSO의 일부 화면이 아니라, Baron SSO를 사용하는 별도 서비스라고 이해하면 된다.

## 3. 설치되는 앱 실행파일은 무엇인가

### 3.1 Android

Android에서 실제 기기에 설치되는 파일은 보통 아래 둘 중 하나다.

- `APK`
- `AAB`에서 스토어가 기기별로 풀어 배포한 설치 패키지

개발/테스트 단계에서는 보통:

- `flutter run`
- debug `APK`

를 사용한다.

운영 배포 관점에서는 보통:

- 사내 직접 배포면 `APK`
- Play Store 배포면 `AAB`

형태를 생각하면 된다.

현재 저장소 문맥상 Android 테스트에서는 debug APK를 직접 깔 수도 있지만, 기능 검증은 `flutter run` 중심으로 하도록 정책이 잡혀 있다. 이유는 이 앱이 실행 시점에 `TDC114_API_BASE` 같은 환경값을 함께 받아야 하기 때문이다.

### 3.2 iOS

iOS에서 실제 설치/배포에 쓰이는 것은 보통:

- 개발기기 설치용 app bundle
- TestFlight/App Store 배포용 `IPA`

라고 보면 된다.

즉 정리하면:

- Android는 주로 `APK` 또는 스토어용 `AAB`
- iOS는 주로 `IPA` 또는 TestFlight/App Store 배포

다.

## 4. 앱 실행파일 자체가 RP인가

이 질문은 자주 헷갈릴 수 있는데, 가장 쉬운 답은 아래와 같다.

- "앱 실행파일 그 자체"를 좁게 보면 그냥 설치 패키지다.
- 하지만 "그 앱 서비스 전체"를 넓게 보면 Baron SSO 입장에서는 하나의 `RP`다.

즉:

- `APK`, `IPA`는 설치물이다.
- 그 설치물을 통해 동작하는 `tdc114plus` 앱 서비스가 Baron SSO에 연동되는 `RP`다.

따라서 팀 내 설명에서는 아래처럼 말하면 가장 덜 헷갈린다.

`tdc114plus` 모바일 앱은 Baron SSO에 등록된 별도 RP이며, 사용자는 Android/iOS 기기에 그 RP의 클라이언트 앱을 설치해 사용한다.

## 5. 앱이 설치된 뒤 실제로 어떻게 동작하는가

네, 큰 흐름은 아래 이해가 맞다.

1. 사용자가 각 모바일 디바이스에 신규앱을 설치한다.
2. 사용자가 앱을 실행한다.
3. 앱은 Baron SSO 관련 API로 로그인 요청을 보낸다.
4. Baron SSO가 로그인 승인 절차를 처리한다.
5. 로그인 완료 후 Baron SSO가 세션 토큰과 사용자 정보를 앱에 돌려준다.
6. 앱은 그 세션으로 직원검색, 조직도, 사용자 표시 정보를 다시 조회한다.
7. 앱 화면은 Baron SSO가 준 로그인 결과와 조직/직원 데이터를 사용자에게 보여준다.

즉, "설치된 실행파일이 Baron SSO와 데이터를 주고받으면서 로그인과 표시 내용을 가져온다"는 이해는 맞다.

다만 더 정확히 말하면:

- 로그인 결과 일부는 앱 내부에 저장된다
- 이후 필요한 화면 데이터는 Baron SSO 연동 API를 다시 호출해서 가져온다

## 6. 어떤 데이터들을 주고받는가

## 6.1 로그인 시작 시 앱 -> Baron SSO

신규앱은 로그인 시작 시 아래 API를 호출한다.

```http
POST /api/v1/tdc114plus/auth/link/init
Content-Type: application/json
Accept: application/json
```

예시 요청:

```json
{
  "phoneNumber": "01012345678",
  "device": {
    "platform": "android",
    "appVersion": "0.1.0",
    "deviceName": "Pixel 8"
  }
}
```

의미:

- `phoneNumber`: 로그인하려는 사용자 전화번호
- `device.platform`: android / ios 같은 플랫폼 정보
- `device.appVersion`: 앱 버전
- `device.deviceName`: 기기명 또는 기기 구분용 값

즉 앱은 "어떤 사용자가, 어떤 기기에서 로그인하려는지"를 JSON 형식으로 Baron SSO에 보낸다.

## 6.2 로그인 시작 응답 시 Baron SSO -> 앱

예시 응답:

```json
{
  "status": "pending",
  "pendingRef": "pending-ref",
  "expiresIn": 180,
  "interval": 3,
  "resendAfter": 30,
  "provider": "Ory (Kratos/Hydra)"
}
```

의미:

- `status`: 현재 로그인 진행 상태
- `pendingRef`: 이 로그인 요청을 나중에 다시 조회할 때 쓰는 참조값
- `expiresIn`: 몇 초 뒤 만료되는지
- `interval`: 몇 초 간격으로 상태 조회할지
- `resendAfter`: 재발송 가능 시간
- `provider`: 내부 인증 제공자 정보

핵심은 Baron SSO가 이 단계에서 바로 로그인 완료를 주는 것이 아니라, "지금은 승인 대기 중이니 이 `pendingRef`로 다시 물어봐라"라고 알려준다는 점이다.

## 6.3 로그인 상태 확인 시 앱 -> Baron SSO

신규앱은 아래 API로 승인 완료 여부를 계속 조회한다.

```http
POST /api/v1/tdc114plus/auth/link/poll
Content-Type: application/json
Accept: application/json
```

예시 요청:

```json
{
  "pendingRef": "pending-ref"
}
```

즉 앱은 복잡한 로그인 정보를 매번 보내지 않고, 처음 받은 `pendingRef`만 보내서 "이 건 승인됐나요?"를 확인한다.

## 6.4 승인 대기 중 응답

```json
{
  "status": "pending",
  "code": "authorization_pending",
  "interval": 3
}
```

의미:

- 아직 사용자가 링크를 누르지 않았음
- 앱은 잠시 기다렸다가 다시 poll 해야 함

## 6.5 승인 완료 응답

```json
{
  "status": "ok",
  "session": {
    "status": "ok",
    "token": "baron-sso-session-token",
    "expiresAt": "2026-07-02T12:00:00Z",
    "user": {
      "id": "user-uuid",
      "name": "홍길동",
      "phoneNumber": "+821012345678",
      "tenantId": "tenant-uuid",
      "tenantName": "한맥",
      "tenantSlug": "hanmac",
      "department": "기술연구소",
      "grade": "책임",
      "position": "팀장",
      "jobTitle": "개발"
    }
  }
}
```

의미:

- `token`: 이후 API 호출 때 사용하는 로그인 세션 토큰
- `expiresAt`: 세션 만료 시각
- `user`: 앱 화면 구성에 필요한 로그인 사용자 정보

여기서 사용자 정보는 아래처럼 쓰인다.

- `name`: 화면에 보여줄 사용자명
- `tenantName`, `tenantSlug`: 어느 회사/테넌트 소속인지
- `department`: 본인 부서
- `grade`, `position`, `jobTitle`: 직급/직위/직무

## 6.6 로그인 후 조회하는 업무 데이터

로그인 후에는 아래 같은 업무 데이터를 Baron SSO 연동 API에서 조회한다.

- 직원 목록
- 조직/가족사 목록
- 조직도
- 직원 상세 정보

문서 기준 주요 API는 아래와 같다.

- `GET /api/v1/tdc114plus/directory/employees`
- `GET /api/v1/tdc114plus/organization/tenants`
- `GET /api/v1/tdc114plus/organization/orgchart`

즉 Baron SSO는 로그인만 해주는 것이 아니라, 앱이 필요한 직원/조직 데이터도 함께 제공하는 역할을 한다.

## 7. 데이터 형식은 무엇인가

기본 형식은 HTTP + JSON 이다.

조금 더 풀면:

- 통신 방식: 모바일 앱이 HTTPS API 호출
- 요청 본문 형식: JSON
- 응답 본문 형식: JSON
- 헤더: 보통 `Content-Type: application/json`, `Accept: application/json`

즉 이 앱은 웹페이지를 긁어오는 방식이 아니라, 구조화된 JSON API를 호출해서 데이터를 받는다.

## 8. 세션은 앱 안에 어떻게 저장되는가

코드상 현재 앱은 로그인 성공 시 아래 정보를 저장한다.

- `token`
- `expiresAt`
- `user`

저장 위치는 앱 내부 저장소(`SharedPreferences`)다.

그래서 앱을 다시 켰을 때:

- 저장된 세션이 아직 유효하면 로그인 화면을 건너뛴다
- 세션이 없거나 만료되면 다시 Baron SSO 로그인으로 보낸다

즉 앱은 매 화면마다 처음부터 새 로그인하는 것이 아니라, 받은 세션을 보관했다가 재사용한다.

## 9. 헤드리스 로그인(headless login)이란 무엇인가

가장 쉬운 설명부터 하면:

헤드리스 로그인은 "앱 안에 Baron SSO의 로그인 웹화면을 직접 띄우지 않고, 앱이 API로 로그인 절차를 진행하는 방식"이다.

`headless`를 직역하면 "머리/화면이 없는" 느낌인데, 여기서는:

- 로그인용 별도 웹페이지 중심이 아니라
- 백그라운드 API 호출 중심으로 로그인 절차를 진행한다

는 뜻으로 이해하면 된다.

## 10. 이번 신규앱의 헤드리스 로그인은 왜 특별한가

이번 신규앱 기본 로그인은 단순한 "전화번호 넣고 바로 로그인"이 아니다.

흐름은 아래와 같다.

1. 앱에서 전화번호 입력
2. 앱이 `link/init` 호출
3. Baron SSO가 문자 또는 메일로 승인 링크 발송
4. 사용자가 그 링크를 열어 승인
5. 앱은 `link/poll`로 승인 완료 여부를 반복 확인
6. 승인 완료가 확인되면 Baron SSO가 세션 발급
7. 앱이 세션 저장 후 첫 화면 진입

즉 핵심은:

- 앱이 로그인 시작을 함
- 최종 승인 행위는 링크 클릭으로 이뤄짐
- 앱은 그 결과를 poll 해서 받아옴

이다.

## 11. 왜 굳이 headless로 하나

장점은 아래처럼 설명할 수 있다.

- 앱 UI를 우리 서비스 스타일에 맞게 단순하게 유지할 수 있다
- 앱 안에서 필요한 로그인 절차를 API 중심으로 제어할 수 있다
- Android/iOS 양쪽에서 같은 로그인 흐름을 구현하기 쉽다

하지만 주의할 점도 있다.

- 앱 코드만 있다고 로그인 검증이 끝나지 않는다
- Baron SSO 쪽에도 `link/init`, `link/poll`, 링크 발송, 승인 상태 변경이 모두 준비되어 있어야 한다
- staging/운영 환경에서 실제 테스트 번호와 링크 수신 경로가 맞아야 end-to-end 검증이 된다

## 12. 헤드리스 로그인과 일반 웹 로그인 차이

일반적인 웹 로그인 느낌:

1. 로그인 페이지로 이동
2. 아이디/비밀번호 또는 인증수단 입력
3. 브라우저 redirect
4. 로그인 완료

이번 헤드리스 로그인 느낌:

1. 앱 화면에서 전화번호 입력
2. 앱이 API 호출
3. 사용자는 외부로 받은 링크를 열어 승인
4. 앱은 API로 상태를 확인
5. 완료되면 앱이 세션을 저장

즉 사용자 입장에서는 앱 화면이 계속 보이지만, 실제 인증 완료 여부는 서버와 승인 링크 절차가 결정한다.

## 13. "전화번호만 넣으면 바로 로그인"과 같은가

아니다. 이번 기본 흐름은 그것과 다르다.

이번 기본 흐름은:

- 전화번호 입력
- 링크 발송
- 사용자 승인
- 승인 확인 후 세션 발급

이다.

즉 전화번호 입력만으로 즉시 로그인시키는 구조가 아니라, 승인 단계를 끼운 비동기 로그인 구조다.

## 14. 팀원들이 가장 헷갈리지 않게 설명하는 표현

아래 표현을 권장한다.

`tdc114plus`는 Baron SSO에 등록된 별도 모바일 RP 앱이다. 사용자는 Android나 iPhone에 앱을 설치하고, 앱은 Baron SSO의 headless 로그인 API를 호출해 로그인한다. 로그인은 전화번호 입력 후 링크 승인 방식으로 진행되며, 승인 완료 뒤 Baron SSO가 세션 토큰과 사용자 정보를 앱에 돌려준다. 이후 앱은 그 세션으로 직원검색/조직도 같은 데이터를 Baron SSO 연동 API에서 조회해 화면에 표시한다.

## 15. 자주 나오는 질문에 대한 짧은 답

### Q1. 신규앱은 Baron SSO 안에 들어가는가

아니라기보다, Baron SSO를 사용하는 별도 앱이다.

### Q2. 앱 실행파일 자체가 RP인가

설치파일 자체보다는, 그 설치파일로 동작하는 앱 서비스 전체를 RP라고 보는 것이 더 정확하다.

### Q3. Android는 APK로 배포하는가

개발/사내 배포는 APK가 가능하고, 스토어 배포는 보통 AAB를 사용한다.

### Q4. iOS는 APK처럼 설치하는가

아니다. 보통 IPA 또는 TestFlight/App Store 방식이다.

### Q5. 앱이 설치된 뒤 Baron SSO와 계속 통신하는가

그렇다. 로그인할 때도 통신하고, 로그인 후 직원/조직 데이터를 가져올 때도 통신한다.

### Q6. 헤드리스 로그인은 화면이 아예 없다는 뜻인가

아니다. 사용자 화면은 앱에 있다. 다만 Baron SSO의 전통적인 웹 로그인 페이지를 직접 띄우지 않고, 앱이 API로 로그인 절차를 처리한다는 뜻에 가깝다.

## 16. 결론

이번 신규앱은 단말에 설치되는 일반 모바일 앱이지만, 인증과 주요 사용자/조직 데이터는 Baron SSO와의 API 연동에 의존한다. 따라서 이 앱은 "독립 실행은 되지만 독립 인증은 하지 않는 RP 앱"이라고 이해하면 가장 정확하다.

또한 이번 로그인은 단순 즉시 로그인 방식이 아니라 `link/init -> 사용자 승인 -> link/poll -> 세션 저장` 흐름의 headless 승인 로그인이다. 그래서 앱 실행파일만 설치되었다고 끝나는 것이 아니라, Baron SSO 쪽 API와 승인 링크 흐름이 함께 정상 동작해야 비로소 로그인과 첫 화면 진입이 완성된다.