MyDoc/tdc114plus/신규앱(TDC114PLUS)과 Baron SSO 연동 쉬운 설명.md

신규앱과 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를 호출한다.

POST /api/v1/tdc114plus/auth/link/init
Content-Type: application/json
Accept: application/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 -> 앱

예시 응답:

{
  "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로 승인 완료 여부를 계속 조회한다.

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

예시 요청:

{
  "pendingRef": "pending-ref"
}

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

6.4 승인 대기 중 응답

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

의미:

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

6.5 승인 완료 응답

{
  "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와 승인 링크 흐름이 함께 정상 동작해야 비로소 로그인과 첫 화면 진입이 완성된다.