kevin/tdc114plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a0d393e338f5064ddc3286c399c430a4b99273cd
tdc114plus/docs/00_guide_tdc114plus_external_api_usage_2026-07-03.md
T

11 KiB
Raw Blame History

tdc114plus 외부 API 사용 및 앱 내 활용 정리

작성일: 2026-07-03 최종 개정일: 2026-07-20 상태: v3.4

목적: tdc114plus 앱이 Baron SSO가 이미 제공하는 API를 어떤 원칙으로 직접 소비해야 하는지, 그리고 어떤 인증값이 앱에 들어가면 안 되는지 정리한다.

상위 기준 문서:

  • docs/00_policy_tdc114plus_development_2026-07-02.md
  • docs/00_contract_tdc114plus_api_2026-07-02.md

1. 한 줄 결론

  • 신규 앱은 Baron SSO에 추가되는 별도 RP다.
  • Baron SSO 원본에 신규앱 전용 /api/v1/tdc114plus/... API를 추가하지 않는다는 현재 기준을 따른다.
  • 단, 앱 비밀값 보호와 모바일 세션 유지를 위해 tdc114plus-auth 중계서버는 별도 운영한다.
  • 앱은 Baron SSO/조직도 사이트가 이미 제공하는 공식 API를 직접 소비하는 클라이언트다.
  • 다만 앱에 넣으면 안 되는 운영 Key나 비밀값은 계속 서버/운영자 전용으로 본다.
  • 현재 코드에 남아 있는 tdc114plus 전용 API 가정은 레거시 흔적으로 보고, 기능 보존 테스트를 동반해 점진 제거한다.

2. 현재 API 계층 해석

2026-07-08 기준 현재 해석은 아래와 같다.

계층 호출 주체 용도 비고
Baron 공개/기존 API Flutter 앱 조직도, 조직/사용자 데이터 조회 Swagger에 노출된 endpoint 기준으로 재확인 필요
Baron 로그인/웹 절차 Flutter 앱 + 사용자 브라우저/링크 RP 로그인, 승인 링크 처리 Hosted Login + PKCE 원칙
운영 Key 기반 외부 연동 API 운영 서버 또는 운영자 원본 데이터 조회 또는 관리자성 연동 모바일 앱 직접 탑재 금지

정리하면, Flutter 앱은 Baron SSO 원본에 신규앱 전용 API를 새로 요구하지 않는다. 대신 앱에 노출되면 안 되는 key/secret, Baron SSO 링크 로그인 중계, 앱 세션 JWT, 프로필 이미지 lookup은 tdc114plus-auth가 맡는다.

3. 신규 앱의 인증 해석

  • tdc114plus는 Baron SSO에 추가되는 별도 RP(Relying Party)다.
  • 앱 로그인은 Baron SSO의 RP 로그인 절차 일부다.
  • 기본 인증 방식은 Baron SSO Hosted Login + OIDC Authorization Code + PKCE다.
  • 흐름은 앱 -> Baron SSO 인증 URL 열기 -> Hosted Login 화면에서 휴대폰번호 입력 -> 문자/메일 링크 인증 -> App Link callback -> token 교환 -> 앱 로그인 완료다.
  • 앱은 승인 링크를 직접 만들지 않고, 휴대폰번호/인증정보도 직접 처리하지 않는다.
  • Swagger의 phone-login, headless, enchanted-link, sms, qr 계열 Auth API는 Baron SSO Hosted Login 화면과 서버 내부 구현의 참고 대상이다.
  • Flutter 앱 기본 구현은 위 Auth API를 직접 조합하지 않고, OIDC authorization endpoint와 token endpoint를 사용한다.
  • 로그인 성공 후 Baron SSO가 조직도 API 호출에 필요한 연동 키 묶음을 전달하면 앱은 이를 선택적 세션 값으로 받아 사용할 준비를 한다.
  • 해당 기능이 Baron SSO에 구현되기 전까지는 staging org-context 검증을 위해 로컬 비추적 env/Dart define의 고정 키 fallback을 사용한다.

2026-07-20 현재 로컬 실기기 검증 흐름에서는 모바일 앱이 Baron SSO 원본을 직접 호출하지 않고 tdc114plus-auth의 아래 중계 API를 호출한다.

POST /api/v1/auth/link/init
POST /api/v1/auth/link/poll
GET /api/v1/integrations/org-context
GET /api/v1/profile-image

위 API는 Baron SSO 원본에 새로 추가한 신규앱 API가 아니라, 신규앱 전용 중계서버 tdc114plus-auth의 API다.

4. 앱이 실제로 호출할 인증 API

현재 저장소 코드에는 아래 레거시 경로 가정이 남아 있거나 제거 대상이다.

POST /api/v1/auth/headless/phone-login
POST /api/v1/auth/headless/link/poll
POST /api/v1/tdc114plus/auth/phone-login

하지만 2026-07-08 사용자 확인 기준으로 tdc114plus 앱 전용 API는 없다.

따라서 위 경로들 중 legacy POST /api/v1/tdc114plus/auth/phone-login을 포함한 레거시 표기는 확정 계약이 아니라 기존 로컬/가정 기반 경로로 격하한다.

처리 원칙:

  1. 먼저 Swagger에서 대응 endpoint를 찾는다.
  2. 그 다음 앱 DTO/repository를 대체 계약으로 맞춘다.
  3. mock/real 테스트와 실제 화면 검증이 끝난 뒤에만 옛 경로를 제거한다.

현재 확정 사실:

  • 신규 앱의 기본 로그인 정책은 Hosted Login + PKCE다.
  • 사용자가 링크를 클릭해야 앱 로그인이 완료된다는 정책은 유지한다.
  • 다만 링크 발송/승인 처리는 앱이 직접 headless API로 수행하지 않고 Baron SSO Hosted Login 화면과 서버 내부 구현에 맡긴다.
  • Swagger에 POST /api/v1/auth/phone-login 또는 POST /api/v1/auth/headless/phone-login이 보이더라도, 앱의 기본 로그인 버튼은 이 API를 직접 호출하지 않는다.

5. 팀장 전달 외부 API 정보의 위치

현재 저장소 기준으로 팀장 전달 정보와 직접 연결되는 외부 연동 대상은 아래 API다.

GET https://sadmin.hmac.kr/api/v1/integrations/org-context
X-Baron-Key-ID: {KEY_ID}
X-Baron-Key-Secret: {KEY_SECRET}

참고:

  • Swagger UI: https://sadmin.hmac.kr/api/docs#/Integrations/get_api_v1_integrations_org_context
  • OpenAPI: https://sadmin.hmac.kr/api/openapi.yaml
  • 로컬 참고 문서: docs/guide_baron_org_context_api_reference_2026-07-03.md

중요 해석:

  • 이 API는 앱 화면을 구성할 때 참고해야 하는 원본/공식 문서 계층이다.
  • 장기적으로는 로그인 성공 후 Baron SSO가 내려주는 조직도 API 연동 키를 사용한다.
  • 단기적으로는 Baron SSO의 키 전달 기능이 아직 미개발이므로, 개발/검증용 staging 고정 키를 로컬 비추적 env/Dart define에만 둔다.
  • tracked 문서, tracked 소스, 운영 APK 기본값에는 X-Baron-Key-ID, X-Baron-Key-Secret 실제 값을 넣지 않는다.

6. 앱이 실제로 호출하는 데이터 API

현재 저장소 코드에는 아래 레거시 데이터 경로 가정이 남아 있다.

GET /api/v1/tdc114plus/directory/employees
GET /api/v1/tdc114plus/directory/employees/{employeeId}
GET /api/v1/tdc114plus/organization/tenants
GET /api/v1/tdc114plus/organization/orgchart

하지만 이 역시 확정 계약으로 보지 않는다.

현재 확인된 근거:

  • sadmin.hmac.kr는 org-context 참고 host이지 tdc114plus 앱 route host는 아니다.
  • sorg.hmac.kr/login?returnTo=%2Fchart는 웹 로그인 진입 주소이며 JSON API가 아니라 HTML 응답을 돌려준다.
  • Swagger 화면에는 Public /api/v1/public/orgchart 같은 조직도 관련 공개 API 흔적이 보인다.

따라서 앞으로의 기준은 아래와 같다.

  1. 조직도/가족사/사용자 조회는 Swagger에 실제로 존재하는 integrations/org-context, public/orgchart 기준으로 다시 잡는다.
  2. 현재 코드의 /api/v1/tdc114plus/... 경로는 전면 재확정 대상이다.
  3. 정확한 path, query, 응답 스키마가 확인되기 전에는 코드 경로를 확정 표현으로 문서화하지 않는다.
  4. 레거시 경로 정리는 유지, 교체, 제거 분류표를 먼저 만든 뒤 순차적으로 수행한다.

7. 원본 외부 API와 앱 기능의 연결

원본 정보 앱 또는 중간 가공 결과 앱 기능
조직 트리 org-context 또는 공개 orgchart 응답을 앱 내부 모델로 매핑 회사/조직 구조 표시
조직 목록 상단 칩용 tenant/company 모델 상단 필터 칩
조직 구성원 직원 목록/상세용 앱 모델 직원검색, 상세
사용자 전화번호 phoneNumber, phoneDisplay 전화/문자 실행
사용자 이메일/직급/직위/직무 동일 또는 유사 필드 상세 정보 표시

즉, 앱은 Swagger에 드러나는 원본/공개 응답을 앱 화면용 모델로 직접 매핑하는 구조로 전환될 수 있다.

8. 환경변수 및 보안 원칙

앱 측 런타임 값:

  • SSO_BASE_URL
  • TDC114_API_BASE
  • APP_VERSION

서버 측 외부 API 연동 값 예시:

TDC114PLUS_ORG_CONTEXT_BASE_URL=https://sadmin.hmac.kr
TDC114PLUS_ORG_CONTEXT_KEY_ID=
TDC114PLUS_ORG_CONTEXT_KEY_SECRET=
TDC114PLUS_ORG_CONTEXT_TENANT_SLUG=hanmac-family
TDC114PLUS_ORG_CONTEXT_INCLUDE_USERS=true
TDC114PLUS_ORG_CONTEXT_INCLUDE_USER_IDS=true

추가 메모:

  • 2026-07-10 기준 팀장 지시에 따라 원본 Baron API 기준 host는 https://sadmin.hmac.kr/를 사용한다.
  • 팀장 전달 운영 키(CLIENT ID, X-Baron-Key-Secret)는 로컬 비추적 env에만 반영하고 tracked 문서에는 직접 기록하지 않는다.
  • 실제 배포 전까지 신규앱에서 사용하는 Baron SSO API 참고 기준은 staging Swagger https://sadmin.hmac.kr/api/docs#/다.

보안 원칙:

  • X-Baron-Key-ID, X-Baron-Key-Secret 실제 값은 tracked 앱 소스와 tracked 문서에 넣지 않는다.
  • 개발/검증 중 Baron SSO가 키 전달 기능을 제공하기 전까지는 비추적 env/Dart define fallback으로만 제한 사용한다.
  • 운영 APK에서는 로그인 성공 후 받은 세션 기반 연동 키 또는 별도 안전한 서버 중계 방식으로 전환한다.
  • 앱에는 공개 가능한 RP Client ID, issuer, redirect URI 같은 공개 설정만 기본값으로 둔다.
  • RP 비밀값, 승인 링크 생성용 내부 인증정보, 외부 API Key는 모두 서버 전용이다.
  • 앱이 저장하는 세션 정보는 운영 전 안전한 저장소 적용 여부를 재검토한다.

9. 팀 공유용 핵심 메시지

  1. tdc114plus는 Baron SSO의 별도 RP다.
  2. 로그인은 Baron SSO Hosted Login + PKCE 방식이며, Baron SSO 화면에서 휴대폰번호 입력 후 사용자가 문자/메일 링크를 클릭해야 앱 로그인이 완료된다.
  3. 앱 전용 tdc114plus backend API는 없다는 현재 기준으로 재정렬한다.
  4. 앱은 Baron이 이미 제공하는 Swagger 공개 API를 직접 소비하는 클라이언트 앱이다.
  5. 운영 Key나 RP 비밀값은 모바일 앱과 저장소 tracked 파일에 두면 안 된다.

10. 현재 기준 주의사항

  • phone-login은 개발용 fallback 경로일 뿐 기본 UX가 아니다.
  • 현재 코드에 남아 있는 /api/v1/tdc114plus/... path는 검증 전 가정일 수 있다.
  • 해당 가정 path 제거는 기능이 유지되는지 테스트한 뒤 단계적으로만 진행한다.
  • 실제 앱 구조는 auth, directory, organization feature별 repository 분리 기준으로 유지하되, endpoint는 Swagger 기준으로 다시 매핑해야 한다.
  • 실제 응답 정합성 검증 중이라, 세부 필드명과 사용 범위는 Swagger 기준으로 계속 재확인해야 한다.
Reference in New Issue View Git Blame Copy Permalink