diff --git a/Baron Safe PWA/WebView 하이브리드 앱 추진 수정안.md b/Baron Safe PWA/WebView 하이브리드 앱 추진 수정안.md index ac3fe58..6777554 100644 --- a/Baron Safe PWA/WebView 하이브리드 앱 추진 수정안.md +++ b/Baron Safe PWA/WebView 하이브리드 앱 추진 수정안.md @@ -4,51 +4,36 @@ ## 1. 목적 -본 문서는 기존 `Baron Safe 기반 휴대폰 승인 로그인 제안안`을 실제 앱 개발로 진행하기 위한 초기 실행 수정안이다. +본 문서는 기존 `Baron Safe 기반 휴대폰 승인 로그인 제안안`을 실제 앱 개발로 진행하기 위한 실행 수정안이다. -Baron SSO의 기존 `userfront`는 그대로 유지하고, 그 안에서 활용 가능한 화면 자산과 -구현 패턴을 Baron Safe 앱 개발 시 가져다 쓰는 방향으로 구상한다. +Baron SSO의 기존 `userfront`는 그대로 유지하고, 그 안에서 활용 가능한 화면 자산, UX 흐름, Flutter 구현 패턴을 Baron Safe 앱 개발 시 가져다 쓰는 방향으로 구상한다. Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱으로 우선 검토한다. -Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱으로 검토한다. - -이 앱은 단순 로그인 화면이 아니라, 등록된 휴대폰을 인증 장치로 사용하여 사용자가 로그인 요청을 확인하고 -승인 또는 거절하는 보안 승인 앱으로 정의한다. +이번 수정안의 핵심은 Baron Safe의 기본 흐름을 `전화번호 입력 시 선승인 후확인 후차단` 방식으로 정의하는 것이다. 즉 사용자가 Baron SSO에서 휴대전화번호를 입력하면 일단 기존 로그인 흐름을 진행하고, Baron Safe 앱에서는 해당 로그인 이력을 즉시 확인할 수 있게 하며, 사용자가 본인 요청이 아니라고 판단하면 앱에서 차단하거나 세션을 해제하는 구조를 기본안으로 둔다. ## 2. 추진 배경 -현재 적용 중인 휴대전화번호 기반 로그인은 사용자 편의성은 높지만, 전화번호만으로는 실제 사용자가 해당 번호의 소유자인지, -현재 로그인 요청을 직접 승인했는지 확인하기 어렵다. +현재 적용 중인 휴대전화번호 기반 로그인은 사용자 편의성이 높다. 다만 전화번호만으로는 사용자가 실제 번호 소유자인지, 해당 로그인 요청이 본인 의사에 의한 것인지 확인하기 어렵다. -이를 보완하기 위해 사용자의 휴대폰에 `Baron Safe` 앱을 설치하고, 해당 앱을 사용자 계정에 사전 등록된 인증 장치로 사용한다. -사용자는 PC, 브라우저, 키오스크 또는 RP 서비스에서 로그인 요청을 시작하고, -휴대폰 앱에서 요청 서비스, 요청 기기, 요청 시간, IP 정보를 확인한 후 승인한다. +이를 보완하기 위해 사용자의 휴대폰에 `Baron Safe` 앱을 설치하고, 해당 앱을 사용자 계정에 연결된 확인 장치로 사용한다. 사용자는 PC, 브라우저, 키오스크 또는 RP 서비스에서 Baron SSO 로그인을 진행하고, 휴대폰 Baron Safe 앱에서 최근 로그인 이력, 연결 앱 현황, 접속 기기, 접속 시간, IP 정보를 확인한다. 본인이 요청한 로그인이 아니거나 의심스러운 경우에는 앱에서 해당 세션 또는 RP 연결을 차단한다. -이 구조는 OpenID Connect CIBA와 유사한 Out-of-Band 인증 흐름이며, Baron SSO의 Hydra/Kratos 기반 인증 흐름과도 연결할 수 있다. +이 방식은 엄격한 사전 승인형 인증보다는 사용성 중심의 사후 확인 및 차단 모델에 가깝다. Baron SSO의 현재 `userfront`에 이미 구현된 `나의 App 현황`, `접속이력`, `현재 세션`, `해지됨` 화면과도 잘 맞는다. ## 3. 기본 방향 `Baron Safe`는 Flutter 기반 설치형 모바일 앱, PWA, WebView/하이브리드 앱 중 하나로 구현할 수 있다. -다만 현재 Baron SSO `userfront`는 이미 모바일 화면을 고려한 포털 UI, 연결 앱 현황, 접속 이력, QR 진입 흐름 등을 포함하고 있다. - -따라서 기존 `userfront`를 직접 변경하거나 앱으로 전환하기보다는, Baron Safe 앱에서 필요한 화면 흐름과 구현 패턴을 가져와 활용하고, - -푸시/생체 인증/보안 저장소 같은 기능은 Baron Safe 앱의 네이티브 또는 Flutter 플러그인 계층으로 보강하는 하이브리드 구조가 적절하다. +현재 Baron SSO `userfront`는 이미 모바일 화면을 고려한 포털 UI, 연결 앱 현황, 접속 이력, QR 진입 흐름 등을 포함하고 있다. 따라서 기존 `userfront`를 직접 변경하거나 앱으로 전환하기보다는, Baron Safe 앱에서 필요한 화면 흐름과 구현 패턴을 가져와 활용하고, 푸시/생체 인증/보안 저장소 같은 기능은 Baron Safe 앱의 네이티브 또는 Flutter 플러그인 계층으로 보강하는 하이브리드 구조가 적절하다. 기본 방향은 다음과 같다. - Android와 iOS를 모두 지원한다. - 기존 Baron `userfront`는 그대로 두고, Baron Safe 앱 개발 시 활용 가능한 Flutter 기술 스택과 UI/상태관리 패턴을 재사용한다. -- 전화번호는 인증 수단이 아니라 사용자 식별자로만 사용한다. -- 실제 인증 근거는 등록된 앱 기기, 기기 private key, 생체 인증 또는 앱 PIN, 승인 응답 서명으로 확보한다. -- 푸시 알림은 로그인 요청을 전달하는 채널일 뿐이며 인증 수단으로 보지 않는다. -- 승인 요청, 승인, 거절, 만료, 실패는 모두 감사 로그로 남긴다. - -따라서 본 수정안에서는 `userfront`를 수정 대상이 아니라, Baron Safe 앱에서 활용 가능한 화면/패턴 자산으로 본다. - -단, 보안 인증 장치 역할에 필요한 private key, 생체 인증, 푸시 수신, 앱 무결성 검증은 WebView 내부 웹 코드만으로 처리하지 않고 - -네이티브 계층 또는 Flutter 플러그인 계층에서 담당하는 방향으로 검토한다. +- 전화번호는 인증 수단이 아니라 사용자 식별자로 사용한다. +- 기본 흐름은 `선승인 후확인 후차단`으로 둔다. +- 사용자는 Baron Safe 앱에서 최근 로그인, 연결 앱, 활성 세션을 확인하고 필요 시 차단한다. +- 푸시 알림은 로그인 발생 사실 또는 위험 이벤트를 사용자에게 알려주는 채널로 사용한다. +- 향후 고위험 RP 또는 관리자 로그인에는 `요청 시 승인/차단` 방식을 선택 적용할 수 있다. +- 확인, 차단, 해제, 만료, 실패는 모두 감사 로그로 남긴다. ## 4. 대상 앱 정의 @@ -56,17 +41,16 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱 주요 역할: -- 사용자 휴대폰을 Baron SSO 인증 장치로 등록 -- 로그인 승인 요청 푸시 수신 -- 로그인 요청 상세 정보 표시 -- 생체 인증 또는 앱 PIN을 통한 사용자 확인 -- 승인 또는 거절 결정 -- 기기 private key를 이용한 승인 응답 서명 +- 사용자 휴대폰을 Baron SSO 계정 확인 장치로 등록 +- 최근 로그인 및 현재 세션 확인 +- 연결된 RP 앱 현황 확인 +- 의심 세션 차단 또는 로그아웃 +- RP 연결 해제 또는 차단 +- 로그인 발생, 신규 기기 접속, 고위험 이벤트 푸시 수신 +- 향후 고위험 로그인에 대한 사전 승인/차단 - 기기 분실, 교체, 해제 대응 -앱은 브라우저에서 열리는 웹앱이 아니라 휴대폰에 설치되는 모바일 앱이다. -라서 사용자의 브라우저가 열려 있을 필요는 없다. -다만 보안상 승인 행위는 사용자가 앱을 열어 직접 수행해야 하며, 백그라운드 자동 승인은 허용하지 않는다. +Baron Safe 앱은 브라우저에서 열리는 단순 웹페이지가 아니라 휴대폰에서 앱처럼 사용하는 모바일 앱이다. 다만 초기 구현은 기존 `userfront`의 화면 자산을 활용하는 PWA 또는 WebView/하이브리드 방식으로 검토한다. ## 5. 지원 플랫폼 및 배포 @@ -99,56 +83,47 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱 | 이미지/SVG | flutter_svg | | 로깅 | logging, logger | -`Baron Safe` 앱은 이 구성을 참고하여 필요한 부분을 가져가되, `userfront` 원본은 그대로 유지한다. -모바일 인증 앱에 필요한 보안/푸시 기능은 Baron Safe 앱 쪽에 별도로 추가한다. +Baron Safe 앱은 이 구성을 참고하여 필요한 부분을 가져가되, `userfront` 원본은 그대로 유지한다. 모바일 앱에 필요한 푸시, 생체 인증, 보안 저장소 기능은 Baron Safe 앱 쪽에 별도로 추가한다. ### 6.2 추가 검토 기술 | 영역 | 권장 기술 | 용도 | | --- | --- | --- | -| Push Notification | firebase_messaging, APNs 연동 | 로그인 승인 요청 알림 수신 | +| Push Notification | firebase_messaging, APNs 연동 | 로그인 발생, 신규 기기 접속, 차단 필요 이벤트 알림 | | Secure Storage | flutter_secure_storage 또는 플랫폼 Method Channel | device id, refresh token, 민감 설정 저장 | -| Private Key Storage | Android Keystore, iOS Keychain/Secure Enclave | 승인 서명용 private key 보호 | -| Local Authentication | local_auth | 지문, Face ID, 기기 PIN 확인 | -| Crypto Signing | JWS/JWK 또는 COSE 지원 라이브러리, 필요 시 네이티브 연동 | 승인 응답 서명 | +| Private Key Storage | Android Keystore, iOS Keychain/Secure Enclave | 향후 승인 응답 서명용 private key 보호 | +| Local Authentication | local_auth | 차단/해제/고위험 승인 전 지문, Face ID, 기기 PIN 확인 | +| Crypto Signing | JWS/JWK 또는 COSE 지원 라이브러리, 필요 시 네이티브 연동 | 향후 승인/차단 요청 위변조 방지 | | API Client | 기존 http 유지 또는 dio 검토 | 앱-SSO API 통신 | -| State Management | flutter_riverpod 유지 | 기기 등록, 승인 요청, 세션 상태 관리 | -| Routing | go_router 유지 | 등록, 승인, 설정 화면 전환 | -| Deep Link | app_links 또는 firebase_dynamic_links 대체 검토 | 푸시/QR/등록 링크 진입 | +| State Management | flutter_riverpod 유지 | 세션, 연결 앱, 알림 상태 관리 | +| Routing | go_router 유지 | 홈, 세션 상세, 차단, 설정 화면 전환 | +| Deep Link | app_links 검토 | 푸시 알림에서 특정 세션/앱 상세로 진입 | | App Integrity | Play Integrity API, DeviceCheck/App Attest 검토 | 위변조 앱과 위험 기기 탐지 | -초기에는 기존 `userfront`와의 일관성을 위해 `flutter_riverpod`, `go_router`, `http`를 유지하는 것이 좋다. -단, 인증 앱 특성상 private key 생성/서명은 일반 secure storage만으로 끝내지 말고 Android/iOS 보안 키 저장소와 직접 연동하는 방안을 검토해야 한다. - ### 6.3 PWA/WebView/하이브리드 방식 검토 -기존 구상은 `userfront`의 활용 가능한 부분을 Baron Safe 앱에서 재사용하여 -PWA 또는 WebView/하이브리드 방식으로 앱처럼 제공하는 방향으로 볼 수 있다. -이 방식은 현재 구현된 모바일 포털 화면과 흐름을 참고할 수 있으므로 초기 개발 속도와 화면 일관성 측면에서 장점이 있다. +기존 구상은 `userfront`의 활용 가능한 부분을 Baron Safe 앱에서 재사용하여 PWA 또는 WebView/하이브리드 방식으로 앱처럼 제공하는 방향으로 볼 수 있다. 이 방식은 현재 구현된 모바일 포털 화면과 흐름을 참고할 수 있으므로 초기 개발 속도와 화면 일관성 측면에서 장점이 있다. | 방식 | 설명 | 장점 | 주의점 | | --- | --- | --- | --- | | PWA | 웹앱을 브라우저 또는 홈 화면 설치 형태로 사용하는 방식 | 배포가 쉽고 기존 `userfront`의 화면/패턴 활용성이 높음 | iOS/Android별 푸시, 백그라운드 동작, 보안 저장소 제약 검토 필요 | -| WebView 앱 | Android/iOS 앱 안에 Baron Safe용 웹 화면을 띄우는 방식 | 앱 설치형 UX 제공, 기존 `userfront`의 화면 흐름을 활용 가능 | 민감 기능은 WebView JS가 아니라 네이티브 브리지에서 처리해야 함 | -| 하이브리드 앱 | 주요 화면은 WebView, 푸시/생체인증/키서명은 네이티브 또는 Flutter 플러그인으로 처리 | 개발 속도와 보안 기능을 절충 가능 | 웹-네이티브 메시지 경계와 인증 토큰 전달 방식 설계 필요 | +| WebView 앱 | Android/iOS 앱 안에 Baron Safe용 웹 화면을 띄우는 방식 | 앱 설치형 UX 제공, 기존 `userfront`의 화면 흐름 활용 가능 | 민감 기능은 WebView JS가 아니라 네이티브 브리지에서 처리해야 함 | +| 하이브리드 앱 | 주요 화면은 WebView, 푸시/생체인증/보안저장은 네이티브 또는 Flutter 플러그인으로 처리 | 개발 속도와 앱 기능을 절충 가능 | 웹-네이티브 메시지 경계와 인증 토큰 전달 방식 설계 필요 | | 순수 Flutter 앱 | Baron Safe 전용 화면과 기능을 Flutter로 별도 구현 | 보안 기능과 앱 UX 제어가 가장 명확함 | 기존 `userfront` 화면 재사용성이 낮고 초기 구현량 증가 | 현 시점의 현실적인 권장안은 하이브리드 방식이다. - `userfront`의 연결 앱 현황, 접속 이력, QR 화면, 기본 포털 UI 중 Baron Safe에 필요한 부분은 Baron Safe 앱 화면으로 활용한다. -- 로그인 승인 알림 수신은 FCM/APNs 기반 네이티브 푸시로 처리한다. -- 승인 전 생체 인증은 Android/iOS 네이티브 또는 Flutter `local_auth` 계층에서 처리한다. -- private key 생성과 서명은 Android Keystore, iOS Keychain/Secure Enclave 계층에서 처리한다. -- WebView 화면은 승인 요청 표시와 사용자 인터랙션을 담당하되, 실제 서명과 민감 토큰 저장은 네이티브 계층에 위임한다. - -즉 `userfront`의 화면/패턴을 Baron Safe 앱에서 활용하더라도 Baron Safe의 인증 근거는 웹 세션 자체가 아니라, -앱에 등록된 기기 키와 네이티브 보안 기능에서 나와야 한다. +- 로그인 발생 알림은 FCM/APNs 기반 네이티브 푸시로 처리한다. +- 차단, 연결 해제, 고위험 승인 전 사용자 확인은 Android/iOS 네이티브 또는 Flutter `local_auth` 계층에서 처리한다. +- 민감 토큰 저장과 향후 기기 서명은 Android Keystore, iOS Keychain/Secure Enclave 계층에서 처리한다. +- WebView 화면은 정보 표시와 사용자 인터랙션을 담당하되, 실제 민감 기능은 네이티브 계층에 위임한다. ## 7. 주요 기능 범위 ### 7.1 1단계 PoC -목표는 전체 보안 완성보다 end-to-end 승인 흐름을 검증하는 것이다. +목표는 전체 보안 완성보다 `전화번호 로그인 후 Baron Safe에서 확인 및 차단` 흐름을 검증하는 것이다. 기능: @@ -157,26 +132,24 @@ PWA 또는 WebView/하이브리드 방식으로 앱처럼 제공하는 방향으 - 기기 등록 요청 - device id 발급 - push token 등록 -- 승인 요청 목록 조회 -- 승인 요청 상세 표시 -- 승인/거절 API 호출 -- 요청 기기 화면에서 poll 방식으로 승인 결과 확인 - -PoC 단계에서는 기기 서명을 단순화할 수 있으나, API 구조는 향후 서명 검증을 추가할 수 있도록 설계한다. +- 최근 로그인/현재 세션 목록 조회 +- 연결 RP 앱 현황 조회 +- 세션 상세 표시 +- 의심 세션 차단 또는 로그아웃 +- RP 연결 해제 또는 차단 +- 로그인 발생 알림 Mock 또는 수동 refresh ### 7.2 2단계 보안형 MVP 기능: -- 앱 기기 등록 시 key pair 생성 -- public key 서버 등록 -- private key는 기기 보안 저장소에 보관 -- 승인 전 생체 인증 또는 앱 PIN 수행 -- 승인 응답 payload 서명 +- 실제 FCM/APNs 푸시 연동 +- 신규 기기 로그인, 외부망 접속, 고위험 RP 접속 알림 +- 차단/해제 전 생체 인증 또는 앱 PIN 수행 +- 차단 요청 payload 서명 - 서버에서 public key로 서명 검증 -- nonce, TTL, 중복 승인 방지 -- 푸시 알림 연동 -- 승인/거절/만료 감사 로그 +- 세션 강제 종료, RP 연결 해제, refresh token 무효화 +- 차단/해제/확인/만료 감사 로그 - 기기 해제 및 재등록 ### 7.3 3단계 운영 확장 @@ -186,7 +159,7 @@ PoC 단계에서는 기기 서명을 단순화할 수 있으나, API 구조는 - 다중 기기 등록 - 기기 분실 신고 및 관리자 강제 해제 - RP별 인증 강도 정책 -- 고위험 로그인 경고 +- 위험 기반 사전 승인 - number matching 또는 request code - FIDO2/passkey 연계 검토 - Play Integrity, App Attest 기반 앱 무결성 검토 @@ -199,66 +172,52 @@ PoC 단계에서는 기기 서명을 단순화할 수 있으나, API 구조는 1. 사용자가 기존 Baron SSO 방식으로 로그인한다. 2. 사용자 설정 화면에서 `Baron Safe 기기 등록`을 선택한다. 3. 서버가 등록용 QR 또는 등록 코드를 생성한다. -4. 사용자가 `Baron Safe` 앱에서 QR 또는 코드를 입력한다. +4. 사용자가 Baron Safe 앱에서 QR 또는 코드를 입력한다. 5. 앱이 기기 정보를 생성하고 push token을 발급받는다. -6. 앱이 기기 key pair를 생성한다. -7. 앱은 public key, device id, push token, platform 정보를 서버에 등록한다. +6. 앱이 필요 시 기기 key pair를 생성한다. +7. 앱은 device id, push token, platform, public key를 서버에 등록한다. 8. 서버는 해당 기기를 사용자 계정에 연결한다. -### 8.2 로그인 승인 +### 8.2 기본 흐름: 전화번호 입력 후 선승인, 확인 후 차단 -1. 사용자가 RP 또는 Baron SSO 로그인 화면에서 휴대전화번호를 입력한다. -2. Baron SSO가 등록 사용자와 등록 기기를 조회한다. -3. Baron SSO가 승인 요청을 생성한다. -4. Baron SSO가 등록 기기에 푸시 알림을 발송한다. -5. 사용자가 휴대폰에서 알림을 누르고 앱을 연다. -6. 앱이 승인 요청 상세를 서버에서 조회한다. -7. 사용자가 요청 서비스, 요청 기기, IP, 시간을 확인한다. -8. 앱이 생체 인증 또는 앱 PIN을 요구한다. -9. 사용자가 승인 또는 거절을 선택한다. -10. 앱이 승인 응답에 서명하여 서버에 제출한다. -11. 서버가 서명, nonce, TTL, 기기 소유관계를 검증한다. -12. 승인 성공 시 Hydra login challenge를 accept하고 RP 로그인을 완료한다. +1. 사용자가 Baron SSO 또는 RP 로그인 화면에서 휴대전화번호를 입력한다. +2. Baron SSO가 전화번호를 정규화하고 등록 사용자를 조회한다. +3. Baron SSO가 기존 정책에 따라 로그인을 진행한다. +4. 로그인 성공 시 Hydra/Kratos 세션과 RP 세션이 생성된다. +5. Baron SSO가 해당 로그인 이벤트를 감사 로그와 세션 목록에 기록한다. +6. Baron SSO가 등록된 Baron Safe 앱으로 로그인 발생 알림을 보낸다. +7. 사용자는 Baron Safe 앱에서 요청 서비스, 접속 기기, IP, 시간, 인증수단을 확인한다. +8. 본인 요청이 맞으면 별도 조치 없이 유지한다. +9. 본인 요청이 아니거나 의심스러우면 앱에서 `차단`, `세션 종료`, `RP 연결 해제`를 선택한다. +10. 앱은 차단/해제 요청 전 생체 인증 또는 앱 PIN을 요구한다. +11. 서버는 차단 요청을 검증한 뒤 해당 세션을 종료하고 필요 시 RP refresh token을 무효화한다. +12. 차단 결과와 후속 조치는 Baron Safe 앱과 감사 로그에 기록된다. -### 8.3 사용자 흐름 제안안 비교 +이 흐름은 사용자 편의성을 우선하면서, 현재 `userfront`에 구현된 앱 현황/접속 이력 화면을 Baron Safe 앱의 핵심 경험으로 활용할 수 있다. -Baron Safe 앱의 사용자 경험은 하나의 방식으로 고정하기보다, 현재 구현된 `userfront`의 연결 앱/접속 이력 흐름과 -향후 앱 승인 흐름을 함께 비교하여 결정하는 것이 좋다. +### 8.3 대안 흐름 비교 -특히 현재 화면에는 `나의 App 현황`, `연동앱`, `해지됨`, `접속이력`, `현재 세션`, `성공/비활성` 등의 정보가 이미 표현되어 있다. -이는 사용자가 사전에 RP 앱 연결을 허용하고, 이후 필요 시 연결을 해지하거나 차단하는 `선승인 후차단` 방식에 가까운 UX로 볼 수 있다. - -반면 Baron Safe 승인 로그인은 사용자가 매 로그인 요청마다 앱에서 승인 또는 차단을 결정하는 `요청 시 승인/차단` 방식에 가깝다. -두 방식은 보안성과 편의성의 균형이 다르므로, 아래와 같이 제안안을 나누어 비교한다. +Baron Safe 앱의 사용자 경험은 기본안 하나로만 고정하지 않고, 보안 수준과 RP 위험도에 따라 몇 가지 대안을 비교한 뒤 단계적으로 적용하는 것이 좋다. | 안 | 방식 | 설명 | 장점 | 단점 | 적합한 용도 | | --- | --- | --- | --- | --- | --- | -| 1안 | 선승인 후차단 | 사용자가 RP 앱을 한 번 연결하면 이후에는 별도 승인 없이 로그인 또는 연동을 허용하고, 사용자는 나중에 앱 현황에서 해지/차단한다. | UX가 가장 간단하고 현재 `userfront` 화면과 잘 맞음. 반복 로그인 피로가 적음. | 최초 연결 이후 개별 로그인 요청을 사용자가 매번 확인하지 않으므로 오인 로그인 탐지가 약함. | 저위험 RP, 내부 포털, 자주 쓰는 업무 앱 | -| 2안 | 로그인 요청 시 승인/차단 | 로그인 요청이 발생할 때마다 Baron Safe 앱으로 알림을 보내고, 사용자가 요청 정보를 확인한 뒤 승인 또는 차단한다. | 보안성이 높고 현재 요청을 사용자가 직접 확인했다는 근거가 명확함. 감사 로그가 강함. | 매번 승인이 필요해 사용자가 번거로울 수 있음. 푸시/앱 안정성이 중요함. | 고위험 RP, 관리자 기능, 외부망 접속, 신규 기기 로그인 | -| 3안 | 최초 1회 승인 후 기간 내 자동 허용 | RP 또는 기기별로 최초 1회만 앱 승인을 받고, 이후 일정 기간은 자동 허용한다. | 보안성과 편의성을 절충할 수 있음. 반복 업무에 적합함. | 신뢰 기간, 기기 변경, 위험 조건 정책이 필요함. | 일반 업무 RP, 동일 기기 반복 로그인 | -| 4안 | 위험 기반 선택 승인 | 평소와 같은 기기/위치/RP는 자동 허용하고, 신규 기기/IP/고위험 RP일 때만 Baron Safe 승인을 요구한다. | 사용자 피로를 줄이면서 위험 상황에는 강한 인증을 적용할 수 있음. | 위험 판단 로직과 정책 관리가 필요함. 초기 구현 난도가 높음. | 운영 단계의 장기 목표 | -| 5안 | QR/코드 매칭 승인 | 로그인 화면에 숫자 코드 또는 QR을 표시하고, 앱에서 같은 코드인지 확인한 뒤 승인한다. | 푸시 피로 공격과 오인 승인을 줄일 수 있음. 사용자가 요청 기기를 더 명확히 확인함. | 사용자가 코드를 비교해야 하므로 UX가 약간 복잡함. | 관리자 로그인, 외부 접속, 키오스크/공용 PC | +| 기본안 | 선승인 후확인 후차단 | 전화번호 입력 후 기존 로그인은 진행하고, Baron Safe에서 사용자가 최근 로그인과 세션을 확인한 뒤 의심 시 차단한다. | UX가 가장 간단하고 현재 `userfront` 화면과 잘 맞음. 반복 로그인 피로가 적음. PoC가 빠름. | 비정상 로그인이 잠시라도 성립될 수 있음. 사후 차단이므로 고위험 RP에는 보완 필요. | 일반 업무 RP, 내부 포털, 저위험 반복 로그인 | +| 2안 | 로그인 요청 시 승인/차단 | 로그인 요청이 발생할 때마다 Baron Safe 앱으로 알림을 보내고, 사용자가 승인해야 로그인이 완료된다. | 보안성이 높고 사용자 승인 근거가 명확함. 오인 로그인 방지에 강함. | 매번 승인이 필요해 번거로움. 푸시 안정성과 앱 응답성이 중요함. | 관리자 기능, 외부망 접속, 고위험 RP | +| 3안 | 최초 1회 승인 후 기간 내 자동 허용 | RP 또는 기기별로 최초 1회만 Baron Safe 승인을 받고, 이후 일정 기간은 자동 허용한다. | 보안성과 편의성을 절충할 수 있음. 반복 업무에 적합함. | 신뢰 기간, 기기 변경, 위험 조건 정책이 필요함. | 일반 업무 RP, 동일 기기 반복 로그인 | +| 4안 | 위험 기반 선택 승인 | 평소와 같은 기기/위치/RP는 기본안으로 처리하고, 신규 기기/IP/고위험 RP일 때만 사전 승인을 요구한다. | 사용자 피로를 줄이면서 위험 상황에는 강한 인증을 적용할 수 있음. | 위험 판단 로직과 정책 관리가 필요함. 초기 구현 난도가 높음. | 운영 단계의 장기 목표 | +| 5안 | QR/코드 매칭 승인 | 로그인 화면에 숫자 코드 또는 QR을 표시하고, 앱에서 같은 코드인지 확인한 뒤 승인한다. | 푸시 피로 공격과 오인 승인을 줄일 수 있음. 사용자가 요청 기기를 더 명확히 확인함. | 사용자가 코드를 비교해야 하므로 UX가 복잡해짐. | 키오스크, 공용 PC, 관리자 로그인 | -### 8.4 권장 사용자 흐름 +### 8.4 권장 적용 순서 -초기 PoC에서는 1안과 2안을 모두 화면상으로 보여주는 방식이 좋다. - -1안은 현재 개발된 `userfront`의 `나의 App 현황`, `접속이력`, `해지됨` 화면을 활용하여 구현한다. -사용자는 이미 연결된 앱과 최근 인증 이력을 확인하고, 필요 시 앱 연결을 해지하거나 차단한다. - -2안은 Baron Safe의 핵심 인증 흐름으로 구현한다. 사용자가 로그인 요청을 하면 앱 또는 WebView 하이브리드 화면에 승인 요청이 표시되고, -사용자가 직접 승인 또는 차단을 결정한다. - -PoC 이후에는 다음과 같은 단계적 적용을 권장한다. +초기 PoC에서는 기본안을 우선 구현한다. | 단계 | 적용 방식 | 설명 | | --- | --- | --- | -| PoC | 1안 + 2안 비교 구현 | 현재 `userfront` 화면과 요청 시 승인 화면을 함께 검증 | -| MVP | 2안 중심, 3안 일부 적용 | 고위험 로그인은 매번 승인, 일반 RP는 일정 기간 신뢰 허용 | -| 운영 | 4안 + 5안 확장 | 위험 기반 정책과 코드 매칭으로 보안 강화 | +| PoC | 기본안 중심 | 전화번호 로그인 후 Baron Safe에서 최근 로그인/세션/RP 연결을 확인하고 차단하는 흐름 검증 | +| MVP | 기본안 + 2안 일부 | 일반 RP는 선승인 후확인 후차단, 고위험 RP 또는 신규 기기는 요청 시 승인/차단 적용 | +| 운영 | 3안 + 4안 + 5안 확장 | 신뢰 기간, 위험 기반 정책, QR/코드 매칭으로 보안 수준 세분화 | -이 구조를 사용하면 팀장 구상인 PWA/WebView 기반 화면 재사용과, -기존 제안안의 Baron Safe 승인 보안 모델을 서로 충돌시키지 않고 함께 발전시킬 수 있다. +이 구조를 사용하면 팀장 구상인 PWA/WebView 기반 화면 재사용과 현재 개발된 `userfront` 화면을 자연스럽게 활용하면서, Baron Safe의 보안 수준을 단계적으로 높일 수 있다. ## 9. 주요 화면 초안 @@ -267,13 +226,14 @@ PoC 이후에는 다음과 같은 단계적 적용을 권장한다. | 온보딩 화면 | Baron Safe 앱 소개 및 시작 | | 기기 등록 화면 | QR 스캔 또는 등록 코드 입력 | | 등록 완료 화면 | 등록된 사용자/기기명 표시 | -| 승인 요청 상세 화면 | 요청 서비스, 요청 기기, IP, 시간, 만료 시간 표시 | -| 생체 인증 확인 | 승인 전 사용자 확인 | -| 승인 완료 화면 | 승인 결과 표시 | -| 거절 완료 화면 | 거절 결과 표시 | -| 요청 없음 화면 | 현재 대기 중인 승인 요청 없음 표시 | -| 기기 설정 화면 | 기기명, 등록일, 마지막 사용 시각, 기기 해제 | -| 보안 설정 화면 | 앱 PIN, 생체 인증 사용 여부 | +| 홈 화면 | 최근 로그인, 현재 세션, 연결 앱 요약 | +| 접속 이력 화면 | 로그인 시간, IP, 기기, 브라우저, 인증수단 표시 | +| 세션 상세 화면 | 세션 ID, RP, 접속 환경, 상태, 차단 버튼 표시 | +| 연결 앱 현황 화면 | 연동 RP 목록, 최근 인증, 연결 해제/차단 | +| 차단 확인 화면 | 생체 인증 또는 앱 PIN 후 차단 실행 | +| 차단 완료 화면 | 세션 종료 또는 RP 연결 해제 결과 표시 | +| 고위험 승인 화면 | 향후 요청 시 승인/차단 방식 적용 시 사용 | +| 보안 설정 화면 | 앱 PIN, 생체 인증 사용 여부, 등록 기기 관리 | ## 10. Backend/API 필요 항목 @@ -298,71 +258,90 @@ POST /api/v1/baron-safe/devices/register - registered_at - user_display_name -### 10.2 승인 요청 생성 API +### 10.2 로그인/세션 이력 조회 API ```text -POST /api/v1/auth/baron-safe/login/init -``` - -요청 항목: - -- phone_number -- login_challenge -- client_id - -응답 항목: - -- auth_req_id -- status -- expires_in -- interval - -### 10.3 앱 승인 요청 상세 조회 API - -```text -GET /api/v1/auth/baron-safe/requests/{authReqId} +GET /api/v1/baron-safe/sessions ``` 응답 항목: -- auth_req_id +- session_id - client_id - client_name -- request_device +- authenticated_at - request_ip_address -- requested_at -- expires_at -- nonce +- user_agent +- auth_method +- status +- is_current -### 10.4 앱 승인/거절 제출 API +### 10.3 연결 앱 조회 API ```text -POST /api/v1/auth/baron-safe/requests/{authReqId}/decision +GET /api/v1/baron-safe/linked-apps +``` + +응답 항목: + +- client_id +- client_name +- linked_at +- last_authenticated_at +- status + +### 10.4 세션 차단/종료 API + +```text +POST /api/v1/baron-safe/sessions/{sessionId}/block ``` 요청 항목: - device_id -- decision -- nonce +- reason - user_presence - user_verification - decided_at - signature -### 10.5 요청 기기 Poll API +응답 항목: + +- status +- terminated_session_id +- revoked_tokens + +### 10.5 RP 연결 해제/차단 API ```text -POST /api/v1/auth/baron-safe/login/poll +POST /api/v1/baron-safe/linked-apps/{clientId}/block ``` +요청 항목: + +- device_id +- reason +- user_presence +- user_verification +- decided_at +- signature + 응답 항목: -- authorization_pending -- approved -- rejected -- expired -- redirect_to +- status +- client_id +- blocked_at + +### 10.6 고위험 로그인 승인 API + +향후 2안 또는 4안을 적용할 경우 다음 API를 추가한다. + +```text +POST /api/v1/auth/baron-safe/login/init +GET /api/v1/auth/baron-safe/requests/{authReqId} +POST /api/v1/auth/baron-safe/requests/{authReqId}/decision +POST /api/v1/auth/baron-safe/login/poll +``` ## 11. 보안 고려사항 @@ -370,55 +349,68 @@ POST /api/v1/auth/baron-safe/login/poll - 앱이 휴대폰 번호를 자동으로 가져오는 방식에 의존하지 않는다. - 전화번호는 사용자 식별자이며 인증 수단이 아니다. +- 기본안은 사후 확인/차단 모델이므로 고위험 RP에는 추가 보완책을 둔다. +- 차단/해제 같은 민감 조작 전에는 생체 인증 또는 앱 PIN을 수행한다. - private key는 서버로 전송하지 않는다. -- 승인 응답은 기기 private key로 서명한다. -- 승인 전 생체 인증 또는 앱 PIN을 수행한다. -- 승인 요청은 짧은 TTL을 가진다. -- nonce는 요청별 1회용으로 사용한다. -- 동일 요청 중복 승인, 만료 후 승인, 다른 기기 승인은 거부한다. +- 차단/승인 응답은 기기 private key로 서명하는 방향을 검토한다. - 푸시 메시지에는 민감정보를 최소화한다. -- 승인 요청 상세는 앱이 서버 API로 조회한다. +- 접속 이력과 세션 상세는 등록된 기기 또는 인증된 사용자만 조회할 수 있어야 한다. - 전화번호 미등록 여부와 기기 미등록 여부가 외부에 노출되지 않도록 응답 메시지를 일반화한다. -- 반복 승인 요청에 대한 rate limit을 적용한다. -- 모든 승인/거절/실패 이벤트를 감사 로그로 남긴다. - +- 반복 로그인 요청 또는 반복 차단 요청에는 rate limit을 적용한다. +- 모든 로그인, 확인, 차단, 해제, 실패 이벤트를 감사 로그로 남긴다. +- 차단 시 Hydra/Kratos 세션, RP 세션, refresh token 무효화 범위를 명확히 정의한다. ## 12. 권장 추진안 -초기에는 기존 `userfront`는 그대로 두고, -그 안에서 활용 가능한 화면 자산과 구현 패턴을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식을 우선 검토한다. -보안 기능은 네이티브 또는 Flutter 플러그인 계층으로 분리하는 것을 권장한다. +초기에는 기존 `userfront`는 그대로 두고, 그 안에서 활용 가능한 화면 자산과 구현 패턴을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식을 우선 검토한다. 보안 기능은 네이티브 또는 Flutter 플러그인 계층으로 분리하는 것을 권장한다. 이유는 다음과 같다. - 현재 `userfront`는 이미 모바일 포털 화면과 연결 앱 현황, 접속 이력, QR 진입 등 Baron Safe와 가까운 화면 흐름을 일부 포함하고 있다. -- 최초 구상은 PWA 또는 WebView/하이브리드 방식으로 현재 화면 자산과 구현 패턴을 Baron Safe 앱에서 활용하는 방향에 가까워 보인다. +- 기본안인 선승인 후확인 후차단은 현재 화면 구조와 가장 잘 맞는다. - 초기 PoC에서는 화면을 전부 새로 만들기보다 기존 `userfront`의 활용 가능한 부분을 가져오는 편이 빠르다. - 다만 푸시, 생체 인증, private key, 보안 저장소, 앱 무결성은 WebView 내부 웹 코드에만 맡기기 어렵다. - 따라서 `userfront`는 유지하고, Baron Safe 앱은 활용 가능한 화면/패턴을 가져오며, 인증 장치 기능은 네이티브/Flutter 앱 계층이 담당하도록 역할을 나누는 것이 적절하다. -단, 장기적으로 Baron Safe가 고보안 인증 앱으로 커질 경우에는 `baron_safe_app` 형태의 별도 Flutter 앱으로 분리하는 방안도 유지한다. -이 경우에도 `userfront`는 그대로 두고 화면과 UX 패턴의 참조 자산으로 활용하며, -앱 패키지, Android/iOS 설정, 푸시 설정, 앱 서명, 보안 저장소 설정은 Baron Safe 앱에서 독립적으로 관리한다. - -따라서 추진 순서는 다음과 같이 잡는다. +추진 순서: 1. 기존 `userfront` 화면 중 Baron Safe 앱에서 활용 가능한 화면, 패턴, API 흐름을 식별한다. 2. PWA 방식과 WebView 앱 방식 중 PoC에 적합한 방식을 결정한다. -3. Backend에 승인 요청 생성, poll, 앱 상세 조회, 승인/거절 API를 추가한다. -4. Mock push 또는 수동 refresh 방식으로 end-to-end 승인 PoC를 완성한다. -5. Android FCM과 iOS APNs 기반 푸시를 연동한다. -6. 생체 인증과 기기 보안 저장소를 네이티브/Flutter 플러그인 계층으로 연동한다. -7. 기기 key pair와 승인 응답 서명 검증을 추가한다. +3. Backend에 세션 이력 조회, 연결 앱 조회, 세션 차단, RP 연결 차단 API를 추가한다. +4. Mock push 또는 수동 refresh 방식으로 기본안 PoC를 완성한다. +5. Android FCM과 iOS APNs 기반 로그인 발생 알림을 연동한다. +6. 차단/해제 전 생체 인증과 기기 보안 저장소를 네이티브/Flutter 플러그인 계층으로 연동한다. +7. 고위험 RP에 한해 요청 시 승인/차단 API를 추가한다. 8. 운영 배포 방식과 장기적으로 완전 별도 `baron_safe_app`으로 갈지 여부를 확정한다. ## 13. 결론 -Baron Safe 앱은 PWA/WebView/하이브리드 방식과 Flutter 기반 별도 앱 방식을 모두 검토할 수 있다. -현재 Baron `userfront`가 이미 모바일 포털 화면을 상당 부분 갖추고 있으므로, -초기 PoC는 `userfront`를 그대로 유지한 채 활용 가능한 화면/패턴/API 흐름을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식이 현실적이다. +Baron Safe 앱의 기본 흐름은 `사용자가 Baron SSO에서 전화번호 입력 → 로그인 선승인 → Baron Safe에서 확인 → 의심 시 차단`으로 잡는 것이 현재 개발된 `userfront` 화면과 가장 잘 맞는다. -다만 본 앱은 일반 화면 앱이 아니라 인증 장치 역할을 하므로, 화면/패턴을 활용하더라도 -푸시, 생체 인증, 기기 보안 저장소, private key 서명, 서버 검증, 감사 로그는 Baron Safe 앱의 핵심 보안 요소로 별도 설계해야 한다. -따라서 PoC 단계에서는 기존 `userfront`의 활용 가능한 부분을 바탕으로 승인 흐름을 빠르게 검증하고, -MVP 단계에서 네이티브 보안 기능과 기기 서명 구조를 반드시 포함하는 방향으로 추진하는 것이 바람직하다. +이 방식은 사용자 편의성과 PoC 속도 측면에서 장점이 크다. 다만 사후 차단 모델이므로 관리자 기능, 외부망 접속, 고위험 RP에는 요청 시 승인/차단, 위험 기반 승인, QR/코드 매칭 같은 대안을 단계적으로 적용하는 것이 바람직하다. + +## 14. 용어 주석 + +### PoC + +PoC는 `Proof of Concept`의 약자이며, 한국어로는 개념 검증 또는 가능성 검증 정도로 볼 수 있다. + +본 문서에서 PoC는 Baron Safe 앱의 전체 보안 기능과 운영 기능을 모두 완성하기 전에, 핵심 흐름이 실제로 가능한지 먼저 확인하는 단계를 의미한다. + +### JWS/JWK + +JWS는 `JSON Web Signature`의 약자이며, JSON 형태의 데이터가 중간에 위조되거나 변경되지 않았음을 서명으로 증명하는 표준이다. + +JWK는 `JSON Web Key`의 약자이며, 공개키 또는 비밀키 정보를 JSON 형식으로 표현하는 표준이다. + +### COSE 기반 + +COSE는 `CBOR Object Signing and Encryption`의 약자이며, 데이터를 서명하거나 암호화하기 위한 표준 형식이다. + +JWS/JWK가 JSON 기반이라면, COSE는 CBOR라는 더 작고 기계 처리에 적합한 데이터 형식을 기반으로 한다. WebAuthn, FIDO2, 패스키 같은 인증 기술에서 자주 사용된다. + +### 앱 private key + +앱 private key는 Baron Safe 앱이 설치된 특정 휴대폰 안에서 생성되고 보관되는 비밀키를 의미한다. + +이 키는 서버로 전송하지 않으며, Android Keystore 또는 iOS Keychain/Secure Enclave 같은 기기 보안 저장소에 보관하는 것이 원칙이다.