kevin/tdc114plus

Fork 0

Files

T

Codex 5d3eee7a16 Stabilize auth flow and profile images

2026-07-20 13:38:39 +09:00

10 KiB

Raw Blame History

tdc114plus API 계약

작성일: 2026-07-02 최종 개정일: 2026-07-10 상태: v3.3

목적: tdc114plus Flutter 앱이 공식 인터페이스 기준으로 설계·개발될 수 있도록 1차 API 계약 원칙과 우선 사용 흐름을 정리한다.

상위 기준 문서:

docs/00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md
docs/00_policy_tdc114plus_development_2026-07-02.md

공식 인터페이스 기준:

Swagger/API Docs: https://sadmin.hmac.kr/api/docs#/
사용자 확인 추가 기준: tdc114plus 앱 전용 API는 없고, Swagger에 공개된 Baron API를 앱이 직접 소비한다.

1. 전제

tdc114plus 신규 앱은 Baron SSO에 등록되는 별도 RP(Relying Party)다.
앱 인증은 Baron SSO의 RP 로그인 절차 일부로 본다.
앱은 Baron SSO 내부 구현이 아니라 공식 API 계약을 기준으로 설계한다.
실제 backend 구현 상태와 무관하게 Flutter 앱은 이 계약을 바탕으로 mock/real 병행 개발이 가능해야 한다.
현재 저장소 코드에 남아 있는 /api/v1/tdc114plus/... 가정은 확정 계약이 아니라 재검증 대상이다.
재검증 대상 경로는 기능이 유지되는지 확인하면서 단계적으로 교체 또는 제거한다.

2. 핵심 원칙

신규 앱의 기본 로그인은 Baron SSO Hosted Login + OIDC Authorization Code + PKCE로 진행한다.
앱은 Baron SSO 인증 URL을 열고, Baron SSO 로그인 화면에서 휴대폰번호 입력 및 문자/메일 링크 인증을 처리한다.
앱은 callback으로 받은 authorization code를 PKCE code_verifier로 token 교환한 뒤 앱 세션을 저장한다.
로그인 성공 후 Baron SSO가 조직도 API 호출에 필요한 연동 키 묶음을 내려주는 구조를 최종 목표로 둔다.
해당 Baron SSO 기능이 개발되기 전까지는 앱 개발/검증용으로 로컬 비추적 환경값에 설정한 staging org-context 키를 fallback으로 사용한다.
기존 선진행 후확인 방식은 신규 앱 기본 인증 정책으로 사용하지 않는다.
기존 phone-login 방식은 개발용 fallback 또는 제한적 호환 범위로만 둔다.
레거시 계약 제거는 대체 path 반영 -> mock/real 테스트 통과 -> 실제 화면 확인 -> 제거 순서를 지킨다.
JSON field는 camelCase를 사용한다.
목록 응답은 가능하면 items, limit, offset, total, nextCursor 형식을 따른다.
UI는 DTO와 repository interface만 의존하고, endpoint path나 header를 직접 다루지 않는다.

3. 1차 범위

Baron SSO Hosted Login 시작
App Link callback 수신
PKCE authorization code token 교환
로그인 세션 저장 후 앱 진입
직원검색
가족사/조직 탐색
조직도
직원 상세
즐겨찾기 로컬 저장

보류:

공지사항
전자결재
수신전화식별
수신팝업
서버 기반 즐겨찾기 동기화

4. 인증 계약

주의:

tdc114plus 앱 전용 API는 없다는 사용자 확인이 들어왔으므로, 아래 계약은 Baron Swagger 기준으로 재정렬한다.
Flutter 앱은 Baron headless API를 직접 호출하지 않는다.
휴대폰번호 입력과 링크 발송/승인은 Baron SSO Hosted Login 화면과 서버 내부 구현으로 둔다.
legacy /api/v1/tdc114plus/... path는 예외 호환 또는 과거 흔적으로만 취급한다.

4.1 로그인 시작

GET https://sso.hmac.kr/oidc/oauth2/auth

의미:

앱이 PKCE code_verifier, code_challenge, state, nonce를 생성한다.
앱이 Baron SSO authorization endpoint를 브라우저/커스텀탭으로 연다.
사용자는 Baron SSO Hosted Login 화면에서 휴대폰번호 입력과 문자/메일 링크 인증을 진행한다.

예시 query:

client_id=39d6190d-72f6-4a58-a84f-cdc5ece3e8af
redirect_uri=https://114.hmac.kr/auth/callback
response_type=code
scope=openid profile email tenants
state={random-state}
nonce={random-nonce}
code_challenge={S256-code-challenge}
code_challenge_method=S256

4.2 callback 수신

GET https://114.hmac.kr/auth/callback?code={authorization-code}&state={state}

의미:

https://114.hmac.kr/auth/callback은 Android App Link로 앱에 연결한다.
앱은 callback의 state가 저장된 PKCE transaction의 state와 같은지 검증한다.
state가 다르면 token 교환을 중단한다.

4.3 token 교환

POST https://sso.hmac.kr/oidc/oauth2/token

의미:

앱은 authorization code와 저장된 code_verifier를 사용해 token endpoint를 호출한다.
PKCE 공개 앱이므로 Client Secret을 보내지 않는다.

예시 요청:

grant_type=authorization_code
client_id=39d6190d-72f6-4a58-a84f-cdc5ece3e8af
code={authorization-code}
code_verifier={stored-code-verifier}
redirect_uri=https://114.hmac.kr/auth/callback

완료 응답 예시:

{
  "access_token": "access-token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "id-token",
  "org_context": {
    "base_url": "https://sadmin.hmac.kr",
    "tenant_slug": "hanmac-family",
    "key_id": "org-context-key-id",
    "key_secret": "org-context-key-secret",
    "expires_at": "2026-07-10T12:00:00Z"
  }
}

org_context는 향후 Baron SSO가 제공할 예정인 확장 필드 예시다. 현재 staging 서버 기능이 미개발이면 응답에 없을 수 있으며, 앱은 이 필드가 없을 때 로컬 비추적 환경값의 staging 고정 키를 사용한다.

4.4 headless API 직접 호출 제외

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

위 API는 Baron SSO 내부 구현 또는 confidential client용 참고 계약으로 본다.
현재 Flutter 앱은 공개 PKCE 앱이므로 client_assertion, private_key_jwt, RP 개인키를 APK에 넣지 않는다.
따라서 위 API는 신규 앱 기본 로그인 구현에서 직접 호출하지 않는다.

4.5 레거시/개발용 즉시 로그인

POST /api/v1/tdc114plus/auth/phone-login

이 경로는 개발용 fallback 또는 제한적 호환 범위로만 본다.
신규 앱 기본 로그인 UX로 간주하지 않는다.

5. 세션 및 사용자 정보

5.1 세션 저장 기준

token 교환 성공 시 반환된 access token과 만료시간을 앱 저장소에 저장한다.
사용자 정보는 id_token claim 또는 후속 userinfo 응답에서 가져온다.
조직도 API 호출용 연동 키가 token 응답, userinfo, 또는 별도 session endpoint로 전달되면 앱 세션의 선택적 orgContextCredential로 저장한다.
orgContextCredential이 있으면 integrations/org-context 호출 시 이 값을 우선 사용하고, 없으면 개발/검증용 비추적 환경값 fallback을 사용한다.
연동 키는 로그에 출력하지 않고, 운영 배포 전에는 안전 저장소 적용 여부를 별도 검토한다.
앱 재실행 시 저장 세션이 유효하면 로그인 화면을 건너뛴다.
API 호출 중 401/403이 발생하면 세션 정리 후 재로그인 흐름으로 돌린다.

5.2 사용자 기본 정보

로그인 완료 후 앱이 기대하는 최소 사용자 정보:

{
  "id": "user-uuid",
  "name": "홍길동",
  "phoneNumber": "+821012345678",
  "tenantId": "tenant-uuid",
  "tenantName": "한맥",
  "tenantSlug": "hanmac",
  "department": "기술연구소",
  "grade": "책임",
  "position": "팀장",
  "jobTitle": "개발"
}

6. 조직/직원 데이터 계약 원칙

직원검색과 조직도는 공식 인터페이스가 제공하는 조직/직원 endpoint를 기준으로 설계한다.
실제 배포 전까지 조직/직원 API 기준은 staging Swagger(https://sadmin.hmac.kr/api/docs#/Integrations/get_api_v1_integrations_org_context)와 staging org-context endpoint를 따른다.
가족사/조직 탐색은 tenant 계층과 tenantSlug를 기준으로 진행한다.
로그인 직후 기본 범위는 사용자의 회사급 tenantSlug를 우선 기준으로 한다.
화면 정책상 필요한 drilldown 구조는 repository 계층에서 정리하고 UI는 결과 모델만 소비한다.
현재 /api/v1/tdc114plus/organization/*, /api/v1/tdc114plus/directory/* 같은 path는 확정 계약이 아니라 placeholder 성격일 수 있으므로, Swagger의 실제 공개 path인 integrations/org-context, public/orgchart 기준으로 교체한다.
교체 전까지는 mock과 실제 화면이 같은 결과를 내는지 확인해 기능 공백 없이 전환한다.

6.1 subtree 계약 보강 필요사항

회사 선택 후 부서 -> 팀 -> 개인 drilldown을 구현하려면 조직 subtree 조회 계약이 필요하다.
현재 API가 최상위 tenant 위주 응답만 제공하는 경우, 앱은 fallback으로 회사 단위 직원 목록과 본인팀 synthetic chip만 유지한다.
Swagger의 public/orgchart처럼 tenants[], users[] 중심 응답을 사용할 경우에도, 최종 목표 계약은 해당 배열만으로 특정 tenant 기준 자식 조직 subtree와 leaf 판단 정보를 복원할 수 있는 형태다.
해당 보강 요청은 docs/00_guide_baron_sso_subtree_api_issue_request_2026-07-07.md 초안 기준으로 Baron SSO 이슈로 병행 관리한다.

7. Flutter 구현 해석

auth feature는 Hosted Login authorization URL 생성, PKCE transaction 저장, callback token 교환, 세션 저장 흐름을 우선 구현한다.
directory, organization feature는 org-context 중심 Swagger DTO와 repository interface를 먼저 고정한다.
mock repository는 실제 API 미구현 상태에서도 유지한다.
실제 API 경로와 mock 경로는 동일한 UI 흐름을 만족해야 한다.

8. 문서 갱신 원칙

Swagger 기준이 달라지면 이 문서를 먼저 갱신한다.
새 endpoint를 사용하기 시작하면 request/response 예시를 추가한다.
내부 추정이 아니라 공식 인터페이스에서 확인된 내용만 확정 표현으로 남긴다.
사용자 확인으로 뒤집힌 가정은 즉시 가정 또는 재검증 대상으로 강등한다.

10 KiB Raw Blame History