tdc114plus/신규앱(TDC114PLUS)과 Baron SSO 연동 쉬운 설명.md 추가
This commit is contained in:
@@ -0,0 +1,418 @@
|
|||||||
|
# 신규앱과 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와 승인 링크 흐름이 함께 정상 동작해야 비로소 로그인과 첫 화면 진입이 완성된다.
|
||||||
Reference in New Issue
Block a user