Stabilize auth flow and profile images

2026-07-20 13:38:39 +09:00
parent 57caca8dc8
commit 5d3eee7a16
128 changed files with 28860 additions and 1468 deletions
@@ -0,0 +1,83 @@
+# TDC114PLUS Android App Link 설정 가이드
+
+작성일: 2026-07-09
+상태: debug 공기계 callback 수신 검증 완료
+
+## 1. 목적
+
+Baron SSO가 인증 완료 후 아래 HTTPS 주소로 이동했을 때 Android의 TDC114PLUS 앱이 열리도록 설정한다.
+
+```text
+https://114.hmac.kr/auth/callback
+```
+
+## 2. 앱 설정
+
+| 항목 | 값 |
+| --- | --- |
+| Android package | `kr.co.baron.tdc114plus` |
+| scheme | `https` |
+| host | `114.hmac.kr` |
+| path | `/auth/callback` |
+| App Link 자동 검증 | 사용 |
+
+## 3. 서버 담당자 요청 사항
+
+`docs/references/assetlinks.debug.json` 파일을 아래 공개 주소에 JSON 원문으로 배포한다.
+
+```text
+https://114.hmac.kr/.well-known/assetlinks.json
+```
+
+배포 조건:
+
+- HTTP 상태코드 `200`
+- 리다이렉트 없이 직접 응답
+- `Content-Type: application/json`
+- 로그인이나 쿠키 요구 없음
+- 외부 네트워크와 테스트 공기계에서 접근 가능
+
+## 4. 현재 테스트 APK 지문
+
+```text
+3A:2D:60:48:6F:E5:3A:84:0C:41:14:DC:3A:17:A4:3B:64:E7:DE:A5:10:4A:09:26:0E:DC:5F:49:88:44:71:76
+```
+
+이 지문은 2026-07-09에 빌드한 debug APK용이다. 운영 APK는 운영 서명 인증서의 SHA-256 지문을 같은 배열에 추가해야 한다.
+
+## 5. 검증 순서
+
+1. 서버에서 `assetlinks.json`을 배포한다.
+2. 최신 APK를 공기계에 재설치한다.
+3. Android가 도메인 소유권 검증을 완료하도록 잠시 기다린다.
+4. 아래 주소를 공기계에서 연다.
+
+```text
+https://114.hmac.kr/auth/callback?code=test-code&state=test-state
+```
+
+5. 브라우저나 앱 선택창이 아니라 TDC114PLUS의 `로그인 결과 확인` 화면이 열리는지 확인한다.
+6. 실제 RP Client ID를 앱에 주입한 후 headless 승인부터 OIDC callback까지 E2E를 수행한다.
+
+## 6. 현재 확인 결과
+
+- `http://172.16.8.198:8080/auth/callback`: 정상
+- `https://114.hmac.kr/auth/callback`: 브라우저 응답 정상
+- 최신 debug APK 공기계 설치: 정상
+- App Link 테스트: 앱 선택창 표시
+- `assetlinks.json` 임시 테스트 서버 배포: 정상
+- 외부 HTTPS JSON 응답: HTTP 200, `application/json` 확인
+- 구형 공기계 자동 연결 상태: `undefined`
+- 공기계 테스트 기본 앱 지정 후 callback 실행: TDC114PLUS `.MainActivity` 직접 실행 성공
+- callback 화면에서 `code=test-code` 수신 확인
+- 판정: callback 수신 경로는 검증 완료. 실제 Client ID와 PKCE code 교환 구현이 남아 있음
+
+## 7. RP Client ID
+
+```text
+39d6190d-72f6-4a58-a84f-cdc5ece3e8af
+```
+
+- Client ID는 공개 식별자이므로 debug APK 기본 설정에 포함한다.
+- Client Secret은 APK에 포함하지 않는다.
+- 환경별 Client ID 변경은 `TDC114_OIDC_CLIENT_ID` Dart define을 사용한다.