네이티브 앱 패스키: 네이티브 구현과 WebView 구현 비교

참고: 시스템 WebView와 임베디드 WebView는 종종 결합되어 사용됩니다. 시스템 WebView가 로그인(자동 자격 증명 공유 포함)을 처리한 다음, 임베디드 WebView가 설정에서 패스키 관리를 렌더링합니다.

주요 결정 요소:

• OAuth 기반 로그인인가요? → 시스템 WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• 네이티브 셸에서 웹 인증을 재사용하고 싶으신가요? → 임베디드 WebView (WKWebView, WebKit 1.12.1+가 적용된 Android WebView)
• 네이티브 중심 앱을 구축하시나요? → 네이티브 구현 (Apple AuthenticationServices, Google Credential Manager)

최신 모바일 플랫폼은 네이티브 앱에 패스키를 통합하는 세 가지 고유한 접근 방식을 제공하며, 각각은 사용자 경험, 기술적 복잡성 및 OAuth 호환성에 대한 장단점이 다릅니다.

1. 네이티브 구현: 플랫폼 API(iOS AuthenticationServices, Android Credential Manager)를 사용하여 앱에 직접 패스키 흐름을 구축합니다. 원활한 생체 인증으로 최고의 사용자 경험을 제공하지만 중간에서 높은 수준의 기술 구현 노력이 필요합니다.

2. 시스템 WebView: 플랫폼의 브라우저 구성 요소(iOS ASWebAuthenticationSession / SFSafariViewController, Android Chrome Custom Tabs)를 사용하여 인증을 처리합니다. OAuth 기반 로그인 흐름에 탁월하며 시스템 브라우저와 자격 증명을 공유합니다.

3. 임베디드 WebView: 앱 내에 사용자 정의 가능한 웹 뷰(iOS WKWebView, Android WebView)를 내장하여 네이티브 앱 뼈대와 함께 웹 인증을 재사용합니다. URL 표시줄 없이 네이티브와 같은 모양을 제공하고 웹 뷰 UI에 대한 완벽한 제어를 제공합니다. 패스키 기능을 활성화하려면 권한 및 자격 증명(iOS)과 AndroidX WebKit 1.12.1+(Android)을 통한 WebView 구성 등 추가 설정이 필요합니다.

올바른 선택은 앱의 인증 아키텍처, OAuth 공급자 사용 여부, UI에 대한 제어 수준, 네이티브 중심으로 구축할지 웹 구성 요소를 재사용할지에 따라 달라집니다.

네이티브 패스키 구현은 플랫폼별 API를 사용하여 앱의 UI에 직접 구축된 인증 흐름을 통해 최적의 사용자 경험을 제공합니다. 사용자는 플랫폼 네이티브 대화 상자, 원활한 생체 인식 및 가장 빠른 로그인 시간의 이점을 누릴 수 있습니다.

네이티브 구현을 선택해야 하는 경우:

• 새로운 네이티브 앱을 구축하거나 인증을 네이티브 화면으로 리팩터링하는 경우
• 즉각적이고 조용한 인증으로 가능한 최고의 사용자 경험을 원하는 경우
• 앱 시작 시 자동 패스키 프롬프트: 네이티브 구현은 preferImmediatelyAvailableCredentials를 사용하여 패스키를 사용할 수 있을 때 자동으로 패스키 오버레이 표시할 수 있으므로, 식별자를 입력하지 않고도 가장 빠른 로그인 환경을 제공할 수 있습니다.
• 인증 UI 및 흐름에 대한 완전한 제어가 필요한 경우
• 플랫폼별 구현(iOS Swift, Android Kotlin)에 투자할 의향이 있는 경우

주요 장점: preferImmediatelyAvailableCredentials()

네이티브 구현은 preferImmediatelyAvailableCredentials()를 활용하여 패스키를 사용할 수 있을 때 앱 시작 즉시 나타나는 자동 패스키 오버레이를 생성할 수 있습니다. 이 사용자 이름 없는 흐름은 가능한 가장 빠른 로그인 경험을 제공합니다. 사용자는 식별자를 먼저 입력하지 않고도 즉시 패스키를 볼 수 있습니다. 이 기능은 네이티브 구현 전용이며 WebView 변형에서는 사용할 수 없습니다.

아래 다이어그램은 WebView의 조건부 UI 접근 방식에 비해 네이티브 인증이 어떻게 더 빠른 사용자 여정을 제공하는지 보여줍니다.

네이티브의 자동 오버레이는 앱 실행 시 즉시 인증이 시작되므로 패스키 사용률이 더 높은 우수한 UX를 제공하는 반면, WebView 구현은 사용자가 먼저 입력 필드와 상호 작용해야 합니다.

기술 요구 사항 개요:

네이티브 패스키 통합에는 앱과 웹 도메인 간의 암호화 신뢰가 필요합니다. 이 신뢰가 없으면 OS는 모든 WebAuthn 작업을 거부합니다. 주요 요구 사항:

1. /.well-known/에서 호스팅되는 앱-도메인 연결 파일(App-Domain Association Files)
2. 웹 도메인과 일치하는 올바른 의존 당사자(Relying Party, RP) ID
3. 플랫폼별 기능 (섹션 4에 자세히 설명됨)

주요 이점: 웹사이트에서 생성된 패스키는 앱에서 원활하게 작동하며 그 반대의 경우도 마찬가지입니다.

iOS에서 네이티브로 패스키를 구현하려면 WebAuthn 작업을 위한 API를 제공하는 Apple의 AuthenticationServices 프레임워크가 필요합니다.

주요 구성 요소:

• ASAuthorizationController: 인증 흐름을 관리합니다.
• ASAuthorizationPlatformPublicKeyCredentialProvider: 패스키 요청을 생성합니다.
• 패스키 로그인을 처리하는 세 가지 고유한 UI 모드:
  • 텍스트 필드 로그인: 버튼 제출 시 패스키 로그인이 시작되는 기존의 사용자 이름 필드
  • 패스키 모달 오버레이: 사용 가능한 패스키를 나열하는 OS 대화 상자
  • 조건부 UI: 키보드 위의 QuickType 표시줄에 표시되는 패스키 제안

개발 팁

• AASA 캐싱: Apple은 AASA 파일을 공격적으로(최대 24시간) 캐시하므로 테스트 시 불편할 수 있습니다. 해결 방법: 테스트 기기에서 개발자 모드를 활성화하고 AASA URL에 ?mode=developer를 추가하여 강제로 새로 가져오도록 합니다.
• 성능 테스트: 수백 개의 자격 증명이 포함된 iCloud 계정으로 테스트하여 실제 지연 시간을 관찰하세요. 시스템 오버레이는 저장된 패스키가 많은 경우 약간의 지연이 발생할 수 있습니다.

Android의 네이티브 패스키 구현은 Credential Manager API(또는 이전 버전과의 호환성을 위한 구형 FIDO2 API)를 사용합니다.

엔터프라이즈 Passkey 백서. passkey 프로그램을 위한 실무 가이드, 도입 패턴, KPI.

백서 받기

주요 구성 요소:

• CredentialManager: 모든 자격 증명 작업의 중앙 API
• CreatePublicKeyCredentialRequest: 패스키 등록용
• GetCredentialRequest: 패스키 인증용
• 두 가지 주요 UI 모드:
  • 텍스트 필드 로그인: 버튼 제출 시 패스키 로그인이 시작되는 기존의 사용자 이름 필드
  • 패스키 모달 오버레이: 사용 가능한 패스키를 나열하는 OS 대화 상자

참고: Android는 현재 네이티브 앱에서 iOS의 조건부 UI 키보드 제안 기능이 없습니다(조건부 UI는 웹 앱에서 작동함).

네이티브로 패스키를 구현하는 데에는 다음과 같은 중요한 과제와 학습 내용이 있습니다. OS 수준에서 통합하면 여러 기기 및 OS 버전에 걸쳐 문제가 표면화될 수 있습니다.

1. 예를 들어, 당사 팀은 앱/웹 자격 증명 연결에 사용되는 apple-app-site-association 파일에 대한 Apple의 공격적인 캐싱 문제와 특정 Android OEM 생체 인식 프롬프트의 미묘한 UI 차이와 같은 문제를 겪었습니다.
2. 또한 일부 엔터프라이즈 시나리오에서는 관리 기기의 정책에 따라 패스키 동기화가 비활성화될 수 있다는 점을 고려하세요. iCloud 키체인이나 Google 비밀번호 관리자 동기화가 해제된 회사 환경에서 패스키는 기기에 종속되며 다른 기기로 로밍되지 않습니다. 이는 중요한 시나리오로 대비해야 합니다(예: 사용자가 새 스마트폰을 구매해도 여전히 로그인할 수 있도록 보장).
3. 타사 자격 증명 관리 앱도 흐름에 영향을 줄 수 있습니다. 예를 들어 사용자가 1Password와 같은 비밀번호 관리자를 활성 자격 증명 공급자로 설정한 경우, 플랫폼의 네이티브 자격 증명 관리자보다 우선하여 패스키 생성 및 저장을 가로채는 경우가 많습니다.

원시 플랫폼 API를 사용하여 패스키를 구현할 수도 있지만, 목적에 맞게 빌드된 SDK는 WebAuthn의 복잡성과 엣지 케이스를 처리하고 내장된 원격 측정을 제공하여 개발을 크게 가속화합니다. 또한 SDK는 단위 테스트를 위한 모의 인터페이스를 제공합니다(시뮬레이터에서 생체 인식을 테스트할 수 없으므로 중요함).

권장 사항: 네이티브 구현의 경우, 프로덕션 배포를 통해 발견된 수많은 엣지 케이스를 처리하고 추가 원격 측정 및 테스트를 제공하는 Corbado SDK(iOS Swift Passkey SDK, Android Kotlin Passkey SDK)를 사용하는 것이 좋습니다.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

시스템 WebView는 플랫폼의 네이티브 브라우저 구성 요소를 사용하여 앱 내에서 인증을 처리합니다. 완전한 네이티브 구현과 달리 시스템 WebView는 실제 시스템 브라우저(iOS의 Safari, Android의 Chrome)를 사용하여 웹 콘텐츠를 표시하며, 공유 쿠키, 저장된 자격 증명 및 친숙한 브라우저 보안 표시기를 유지합니다.

시스템 WebView를 선택해야 하는 경우:

• 앱이 OAuth 기반 로그인을 사용하는 경우: 시스템 WebView는 OAuth2/OIDC 흐름에 권장되는 접근 방식이며, 안전한 인증을 제공합니다.
• 모바일 앱에서 재사용하려는 기존 웹 기반 인증이 있는 경우
• 네이티브로 다시 빌드하지 않고 여러 인증 방법(비밀번호, 소셜 로그인, 패스키)을 지원해야 하는 경우
• 웹과 모바일 전반에 걸쳐 단일 인증 코드베이스를 유지하려는 경우

주요 장점:

• OAuth 호환성: OAuth/OIDC 인증 흐름을 위해 특별히 제작되었습니다.
• 보안 표시기: 사용자는 실제 URL과 SSL 인증서를 볼 수 있어 신뢰를 쌓을 수 있습니다.
• 낮은 구현 노력: 최소한의 네이티브 코드만 필요합니다.
• 일관된 UX: 사용자가 이미 신뢰하는 익숙한 브라우저 인터페이스

플랫폼 구성 요소:

• iOS: ASWebAuthenticationSession(인증 흐름에 권장) 또는 SFSafariViewController(일반 브라우징)
• Android: Chrome 맞춤 탭 (CCT)

Google 및 GitHub와 같은 주요 기업은 기존 웹 인증 페이지에 WebView 오버레이를 통해 모바일 앱에 패스키 로그인을 추가하는 데 이 접근 방식을 채택했습니다. 이는 완전한 네이티브 인증 재구축을 당장 실행할 수 없을 때 효과적입니다.

iOS는 인증을 위해 두 가지 주요 시스템 WebView 구성 요소를 제공합니다.

ASWebAuthenticationSession (인증 시 권장):

• OAuth/OIDC 및 보안 로그인 흐름을 위해 특별히 제작됨
• 앱이 인증을 원한다는 메시지를 사용자에게 자동으로 표시
• Safari와 쿠키 및 자격 증명 공유
• iCloud 키체인을 통한 패스키 지원

SFSafariViewController (일반 브라우징):

• 앱 내에서 완전한 Safari 경험 제공
• URL 표시줄 및 보안 표시기 표시
• iOS 11+에서는 Safari 쿠키를 공유하지 않음; Safari 세션 공유가 필요할 때는 ASWebAuthenticationSession 사용
• 사용자 정의 가능성은 낮지만 사용자에게 더 큰 신뢰를 줌

앱이 OAuth 기반 로그인을 사용하는 경우, ASWebAuthenticationSession은 인증 시나리오를 위해 특별히 설계되었고 보안과 사용자 경험의 최상의 균형을 제공하므로 권장되는 선택입니다.

Chrome 맞춤 탭(CCT)은 앱 내에서 Chrome 기반의 인증 경험을 제공합니다.

주요 기능:

• Chrome 브라우저와 쿠키 및 자격 증명 공유
• URL 및 보안 표시기 표시
• 툴바 색상 및 브랜딩 사용자 지정 가능
• 더 빠른 로드 시간을 위한 사전 준비(Pre-warming)

OAuth 통합: Chrome 맞춤 탭은 iOS ASWebAuthenticationSession과 동등한 Android 기능으로, 저장된 패스키에 대한 액세스를 유지하면서 뛰어난 OAuth 지원을 제공합니다.

라이브 데모에서 passkeys를 체험하세요.

Passkeys 체험하기

임베디드 WebView는 앱 내 웹 콘텐츠 렌더링에 대한 완벽한 제어를 제공하여, URL 표시줄 없이 쿠키, 세션 및 탐색을 직접 조작할 수 있게 해줍니다. 그러나 이 제어 권한을 얻으려면 패스키 기능을 활성화하기 위한 추가 기술적 요구 사항을 충족해야 합니다.

임베디드 WebView를 선택해야 하는 경우:

• 네이티브와 같은 경험: 앱이 이미 사용자 지정된 웹 뷰 내에 인증을 내장하여 네이티브의 룩앤필을 유지하고 있으며, 이 일관된 사용자 경험을 유지하려는 경우
• 세션/쿠키 제어 필요: 앱이 OAuth 인증 완료 후 인증 토큰 및 세션 상태를 직접 조작해야 하는 경우
• 시스템 WebView 인증이 인증 코드를 반환하지만 임베디드 컨텍스트에 세션이 없는 기존 인증 흐름
• 여러 임베디드 웹 화면에 걸쳐 인증된 상태를 유지해야 하는 경우
• 자사 인증 전용: 앱이 인증을 직접 처리합니다. 타사 패스키 구현에 대해서는 여기를 참조하세요.
• 런타임 기능 감지가 포함된 AndroidX WebKit 1.12.1+
• 로그인에 대한 조건부 UI 제한(임베디드 WebView에서 지원되지 않음) 허용, 관리 설정에는 관련 없음

중요한 배경 설명:

많은 앱이 하이브리드 접근 방식을 사용합니다. 시스템 WebView가 초기 OAuth 인증(패스키가 원활하게 작동함)을 처리한 다음, 설정에서 패스키를 관리하기 위해 인증 후 임베디드 WebView로 전환합니다. 임베디드 WebView 내에서 패스키를 직접 사용하려 할 때 문제가 발생합니다.

기술 요구 사항:

임베디드 WebView는 시스템 WebView에 비해 추가 설정이 필요합니다.

1. iOS: 관련 도메인(Associated Domains) 자격 증명, AASA 파일 구성
2. Android: 패스키 기능을 활성화하기 위한 WebView WebAuthn 구성(기능 감지 필요)이 포함된 AndroidX WebKit 1.12.1+
3. 공통: 올바르게 구성된 잘 알려진 연결 파일 및 Digital Asset Links

플랫폼 구성 요소:

• iOS: WKWebView
• Android: android.webkit.WebView

장단점:

• 중간 복잡성: WebView 구성(Android WebKit 1.12.1+) 및 권한 설정(iOS) 필요
• 낮은 패스키 채택률: 네이티브에 비해 사용자가 더 많은 마찰을 겪을 수 있음
• 조건부 UI 지원 안 됨: 입력 필드의 패스키 자동 완성 기능이 Android 임베디드 WebView에서 작동하지 않음
• 제한된 플랫폼 지원: 일부 기능이 일관되게 작동하지 않을 수 있음(예: 자동 패스키 생성)

WebView를 통해 패스키를 구현할 때 시스템 WebView와 임베디드 WebView의 차이를 이해하는 것이 중요합니다. 위에 설명된 세 가지 접근 방식(네이티브 구현, 시스템 WebView 및 임베디드 WebView)은 각각 서로 다른 사용 사례를 제공합니다.

iOS에서는 인앱으로 웹 콘텐츠를 표시하는 여러 옵션이 있습니다.

• WKWebView는 WebKit 프레임워크(iOS 8에 도입됨)의 일부인 사용자 정의 가능한 WebView입니다. 개발자는 웹 콘텐츠의 모양과 동작을 높은 수준으로 제어할 수 있습니다.
• SFSafariViewController는 앱 내에서 가벼운 Safari 브라우저 역할을 하는 Apple에서 제공하는 뷰 컨트롤러입니다. Safari 엔진을 사용합니다. iOS 11+에서는 별도의 쿠키 저장소가 있으며 Safari 쿠키를 공유하지 않습니다. Safari 세션 공유가 필요할 때는 ASWebAuthenticationSession을 사용하세요.
• SFAuthenticationSession / ASWebAuthenticationSession은 OAuth/OpenID 또는 기타 보안 로그인 흐름을 위해 특별히 고안된 특수 웹 인증 세션(iOS 11/12부터 사용 가능)입니다. 이들도 기본적으로 Safari를 활용하지만 인증 흐름에 초점을 맞추고 공유 쿠키 및 SSO(Single Sign-On)와 같은 기능을 자동으로 처리합니다.

Android에서의 주요 선택 사항은 다음과 같습니다.

• Android WebView는 액티비티에 내장할 수 있는 미니 브라우저인 표준 WebView 위젯(android.webkit.WebView)입니다. 사용자 정의가 가능하지만 앱의 프로세스 내에서 실행됩니다.
• **Chrome 맞춤 탭(CCT)**은 앱 컨텍스트 내에서 Chrome 기반의 탭을 여는 기능입니다. 맞춤 탭은 앱의 일부로 표시되지만 사전 로드, 공유 쿠키, 사용자 신뢰를 위한 익숙한 URL 표시줄 등 Chrome 브라우저(설치된 경우)에 의해 구동됩니다.

다음 섹션에서는 iOS 및 Android용 WebView 유형에 대해 더 자세히 살펴보고, 패스키 인증 흐름에 가장 적합한 것이 무엇인지 논의하겠습니다.

최신 뉴스를 위해 Passkeys Substack을 구독하세요.

구독하기

Apple의 플랫폼은 위에 나열된 세 가지 WebView 옵션을 제공합니다. 선택에 따라 앱 내에서 패스키가 얼마나 원활하게 사용될 수 있는지가 결정됩니다.

iOS에서 다양한 WebView 동작을 테스트하려면 앱 WebView - WKWebView and UIWebView rendering을 권장합니다.

WKWebView는 iOS용 다목적 WebView 구성 요소입니다. 개발자는 UI 및 동작에 대한 높은 수준의 제어 기능을 통해 WKWebView를 임베드하여 웹 콘텐츠를 렌더링할 수 있습니다. WKWebView는 Safari와 동일한 렌더링 엔진을 사용하므로 성능이 매우 뛰어나고 최신 웹 기능을 지원합니다. 이론적으로 WKWebView는 올바르게 구성되면 WebAuthn(따라서 패스키)을 처리할 수 있지만, 보안을 위해 일부 고급 브라우저 기능이 제한될 수 있습니다. 주의해야 할 한 가지는 WKWebView가 기본적으로 모바일 Safari와 쿠키나 키체인 데이터를 공유하지 않는다는 점입니다. WebView 세션이 Safari의 세션과 격리되어 있으므로 사용자는 새로 로그인해야 할 수 있습니다. 또한 앱에서 WKWebView 콘텐츠를 완전히 사용자 지정할 수 있으므로 사용자에게 주소 표시줄이나 Safari UI가 표시되지 않습니다. 이는 브랜딩에는 좋지만 페이지의 적법성을 확인할 수 있는 단서가 적어짐을 의미합니다(피싱 방지에 대한 우려). 일부 앱은 스크립트를 주입하거나 콘텐츠를 변경하기 위해 WKWebView를 남용한 적이 있으므로(예: TikTok이 인앱 브라우저를 통해 추적 JS를 주입한 것으로 나타남) WKWebView를 안전하고 사용자가 신뢰할 수 있는 방식으로 사용하도록 주의해야 합니다.

SFSafariViewController는 인앱 Safari 경험을 제공합니다. SFSafariViewController를 사용하여 URL을 여는 것은 실제 Safari 브라우저에서 여는 것과 거의 동일하지만 사용자가 앱의 UI 내에 머문다는 점이 다릅니다. 패스키에 대한 장점은 큽니다. 근본적으로 Safari이므로 사용자의 iCloud 키체인과 저장된 패스키에 액세스할 수 있습니다. 쿠키는 iOS 11+에서 공유되지 않는다는 점에 유의하세요. 즉, 사용자가 이미 사이트에 대한 패스키를 가지고 있는 경우 Safari는 해당 패스키를 찾아 조건부 UI 자동 완성 기능을 표시하여 쉽게 로그인할 수 있습니다. SFSafariViewController는 사용자 정의 기능은 떨어지지만(도구 모음을 많이 변경할 수 없음) 많은 보안 및 개인정보 보호 기능을 자동으로 처리합니다. URL 표시줄이 HTTPS용 자물쇠 아이콘과 함께 표시되므로 사용자는 올바른 도메인에 있다는 확신을 얻을 수 있습니다. 일반적으로 SFSafariViewController는 원시 WKWebView보다 더 안전한 것으로 간주되며 구현하기도 더 간단합니다(Apple이 드롭인 형태로 제공). 가장 큰 단점은 룩앤필에 대한 일부 제어 권한을 희생한다는 것입니다. 인증 흐름의 경우 이는 일반적으로 허용됩니다. 여기의 최우선 순위는 보안과 로그인 편의성인데, SFSafariViewController는 Safari의 컨텍스트를 사용하여 이를 훌륭하게 수행합니다.

SFAuthenticationSession / ASWebAuthenticationSession - 이러한 클래스(후자는 더 최신의 Swift 친화적인 이름임)는 OAuth 또는 OpenID Connect와 같은 로그인 흐름을 위해 특별히 제작되었습니다. 웹 페이지를 통해 사용자 인증이 필요한 경우(예: 외부 IdP로), 이 세션은 iOS에서 권장되는 선택입니다. 내부적으로 Safari 브라우저를 활용하고 Safari와 쿠키/저장소를 공유한다는 점에서 SFSafariViewController와 매우 유사합니다. 주요 차이점은 SFAuthenticationSession은 항상 앱이 웹페이지를 사용하여 인증을 원한다는 메시지를 사용자에게 표시(사용자 인지를 위해)하고 사용 가능한 경우 사용자의 기존 Safari 세션을 자동으로 사용한다는 점입니다.

이점은 원활한 SSO 경험입니다. 사용자가 Safari의 공급자에 이미 로그인되어 있는 경우 이 세션은 해당 쿠키를 사용하여 다시 로그인하지 않도록 할 수 있습니다. 패스키의 경우 Safari/iCloud 키체인에 저장된 모든 패스키 자격 증명도 여기서 사용할 수 있음을 의미하기 때문에 중요합니다. Apple의 공식 가이드는 로그인 흐름처럼 보이는 모든 항목에 ASWebAuthenticationSession을 사용하는 것입니다. 장점은 개인정보 보호 강화(앱이 자격 증명이나 쿠키를 절대 볼 수 없으며 Safari가 처리함)와 내장된 SSO 지원입니다. 단점은 인증 흐름에 국한된다는 것입니다(앱에서 임의의 웹 콘텐츠를 렌더링하는 데 사용하지 않음). 요약하면, iOS에서 WebView 접근 방식을 선택하는 경우 ASWebAuthenticationSession이 안전하고, Safari와 상태를 공유하며, 인증용으로 특별히 제작되었기 때문에 패스키 구현에 있어 최고의 선택입니다.

실제로 얼마나 많은 사람이 passkeys를 쓰는지 확인하세요.

도입 데이터 보기

Android에서 WebView 결정은 클래식 WebView와 Chrome 맞춤 탭 간의 선택입니다.

Android에서 다양한 WebView 동작을 테스트하려면 앱 WebView vs Chrome Custom Tabs를 권장합니다.

Android WebView(android.webkit.WebView)는 액티비티 레이아웃에 웹페이지를 임베드할 수 있는 구성 요소입니다. 탐색을 가로채거나 JavaScript를 주입하거나 UI를 사용자 지정할 수 있는 등 완전한 제어 권한을 제공한다는 점에서 WKWebView와 유사합니다. 또한 앱의 프로세스 내에서 실행됩니다. 패스키에 WebView를 사용하면 앱이 웹 로그인 페이지를 로드하고 해당 페이지가 WebAuthn 패스키 의식을 시작할 수 있음을 의미합니다. 최신 Android WebView는 WebAuthn을 지원합니다(기기의 WebView 구현이 Android 시스템 WebView 또는 Chrome 구성 요소를 통해 최신 상태라고 가정할 때). 한 가지 주요 고려 사항은 기본적으로 Android WebView는 사용자의 Chrome 브라우저와 쿠키나 저장된 자격 증명을 공유하지 않는다는 점입니다. 따라서 WebView에서 생성되거나 사용된 패스키를 Chrome에서 인식하지 못할 수 있으며 그 반대의 경우도 마찬가지입니다. 이러한 격리는 보안 측면에서는 좋지만(앱에서 브라우저 쿠키를 읽을 수 없음) 사용자가 Chrome에서 이미 인증된 경우 다시 로그인하도록 강요할 수 있습니다. 또 다른 문제는 신뢰입니다. 일반 WebView는 URL이나 SSL 잠금 아이콘을 표시하지 않으므로 사용자는 피싱 당하지 않으리라고 앱을 완전히 신뢰해야 합니다. Google은 잠재적인 피싱 위험을 이유로 Google OAuth 로그인에 WebView 사용을 금지하기도 했습니다. 성능 측면에서 WebView는 괜찮지만, 특히 무거운 페이지를 로드할 때 사용자의 기본 브라우저를 사용하는 것보다 느리거나 메모리 집약적일 수 있습니다.

**Chrome 맞춤 탭(CCT)**은 하이브리드 접근 방식입니다. 앱 내에 속한 것처럼 보이는 Chrome에서 렌더링된 페이지를 앱에서 열 수 있습니다. 툴바 색상을 사용자 지정하거나 앱 로고를 추가하는 등의 작업을 할 수 있지만, 콘텐츠는 별도의 프로세스에서 Chrome에 의해 렌더링됩니다. 패스키와 관련하여 CCT에는 여러 가지 이점이 있습니다. 사용자의 쿠키 및 자격 증명을 Chrome 브라우저와 공유합니다. 즉, 사용자가 Chrome(Google 비밀번호 관리자)을 통해 저장된 패스키를 보유한 경우 맞춤 탭에서 해당 패스키에 액세스할 수 있습니다. 또한 사용자는 실제 URL과 보안 표시기를 볼 수 있으므로 신뢰를 얻을 수 있습니다. 성능이 더 나은 경우가 많습니다. 백그라운드에서 Chrome을 "준비(warmed up)"하여 더 빠르게 로드할 수 있습니다. 그리고 중요한 것은 보안이 강력하다는 것입니다. 본질적으로 Chrome 앱이기 때문에 Google 세이프 브라우징과 같은 기능이 세션을 보호하며 앱에서 임의의 스크립트를 페이지에 주입할 수 없습니다(특정 공격 방지).

단점은 사용자가 Chrome(또는 지원되는 브라우저)을 설치하고 최신 상태로 유지해야 한다는 것입니다. 대부분의 Android 사용자는 그렇지만 일부 지역의 일부 기기에서는 이 점이 문제가 될 수 있습니다. 전반적으로 Android에서 임베디드 웹 접근 방식을 사용하는 경우 통합과 보안 간의 균형이 잘 맞으므로 패스키 흐름에 Chrome 맞춤 탭을 사용하는 것이 좋습니다. 실제로 인증을 위해 기본 브라우저를 활용한다는 점에서 여러모로 iOS의 SFSafariViewController/ASWebAuthSession과 비슷합니다.

(참고: Apple의 WKWebView 대 SFSafariViewController 및 Android의 WebView 대 CCT는 유사점이 많습니다. Safari VC 및 맞춤 탭은 브라우저 상태를 공유하고 더 나은 보안을 제공하는 반면, WKWebView/Android WebView는 더 많은 제어 권한을 제공하지만 웹 콘텐츠를 격리합니다. 패스키의 경우 패스키에 원활하게 액세스하고 생성할 수 있도록 상태(쿠키, 자격 증명 저장소)를 공유하는 것이 일반적으로 바람직합니다.)

선택한 구현 접근 방식에 관계없이 패스키 기능을 활성화하려면 특정 기술적 요구 사항을 충족해야 합니다. 이 섹션에서는 잘 알려진 연결 파일, iOS 권한 부여 및 Android WebView 구성에 대한 종합적인 가이드를 제공합니다.

관리 기기에 대한 참고 사항: 모바일 기기 관리(MDM) 정책이 자격 증명 스토리지를 제어하는 관리 기기에서는 패스키 동작이 크게 달라집니다. 관리 기기에서의 패스키 테스트에 대해서는 관리되는 iOS 및 Android 기기의 패스키를 참조하세요.

네이티브 및 임베디드 WebView 흐름에는 앱과 웹 도메인 간의 암호화 신뢰를 확립하기 위해 연결 파일이 필요합니다. 시스템 WebView(ASWebAuthenticationSession) 및 Chrome 맞춤 탭은 앱-사이트 연결이 필요하지 않습니다.

AASA 파일은 iOS 앱과 웹 도메인 간의 연결을 확립하여 두 플랫폼 모두에서 패스키가 작동할 수 있도록 지원합니다.

파일 위치: https://yourdomain.com/.well-known/apple-app-site-association

구성 요구 사항:

• 귀하의 도메인의 /.well-known/apple-app-site-association에 호스팅
• 유효한 SSL 인증서가 있는 HTTPS를 통해 제공
• Content-Type: application/json
• .well-known 경로에 리디렉션 없음
• 앱의 Team ID와 Bundle ID 포함

AASA 파일 예시:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

AASA 캐싱 및 테스트:

Apple은 CDN을 사용하여 AASA 파일을 매우 공격적으로 캐시(최대 24-48시간)하므로 개발 및 테스트를 방해할 수 있습니다. 개발 중 캐싱을 우회하는 방법은 다음과 같습니다.

1. 테스트 기기에서 개발자 모드를 활성화합니다.
2. Xcode의 관련 도메인(Associated Domains)에 ?mode=developer를 추가합니다.
3. 이렇게 하면 iOS가 서버에서 최신 AASA 파일을 직접 강제로 가져옵니다.

⚠️ 중요: 프로덕션 릴리스에서는 ?mode=developer를 사용하지 마십시오. 이 매개변수는 개발 전용이며 프로덕션에서 사용하면 iOS가 AASA 파일을 제대로 감지하지 못해 패스키 기능이 손상됩니다.

확인: 구성을 확인하려면 Apple의 AASA Validator를 사용하세요.

Android는 Digital Asset Links를 사용하여 앱과 웹사이트 간의 관계를 확인합니다.

파일 위치: https://yourdomain.com/.well-known/assetlinks.json

구성 요구 사항:

• 귀하의 도메인의 /.well-known/assetlinks.json에 호스팅
• 유효한 인증서가 있는 HTTPS를 통해 제공
• Content-Type: application/json
• 앱의 SHA256 지문(서명 인증서의 지문) 포함

assetlinks.json 파일 예시:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

확인: 구성을 생성하고 확인하려면 Google의 Digital Asset Links Generator를 사용하세요.

iOS 앱이 패스키 기능에 액세스하려면 적절한 권한(Entitlements)이 필요합니다. 요구 사항은 구현 접근 방식에 따라 약간 다릅니다.

권한 파일(Flutter 앱의 경우 Runner.entitlements, 네이티브 iOS 프로젝트의 경우 YourApp.entitlements로 종종 명명됨)은 Apple의 시스템이 부여하는 특별 권한 및 기능을 정의합니다. 패스키의 경우 이 파일은 관련 도메인(Associated Domains)을 구성합니다.

파일 위치: 일반적으로 Xcode 프로젝트의 ios/Runner/Runner.entitlements에 있습니다.

네이티브 구현 및 임베디드 WebView에는 앱과 웹 도메인을 연결하기 위한 Associated Domains 기능이 필요합니다. 시스템 WebView(ASWebAuthenticationSession)는 Safari 컨텍스트에서 실행되므로 이 기능이 필요하지 않습니다.

Xcode에서의 설정:

1. Xcode에서 프로젝트를 엽니다.
2. 앱 타겟을 선택합니다.
3. "Signing & Capabilities" 탭으로 이동합니다.
4. "+ Capability"를 클릭하고 "Associated Domains"를 추가합니다.
5. webcredentials: 접두사가 있는 도메인을 추가합니다.

구성 예시:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

여러 도메인: 앱이 여러 도메인에서 작동해야 하는 경우 관련 출처 요청(ROR, Related Origin Requests)이 필요할 수 있습니다.

Android 임베디드 WebView는 WebKit 기반의 최신 접근 방식(섹션 5.3.1)과 기존 JavaScript 브릿지 접근 방식(섹션 5.3.2)이라는 두 가지 뚜렷한 방식을 통해 패스키를 지원합니다. 시스템 WebView(Chrome 맞춤 탭)는 별도 구성이 필요하지 않으며 자격 증명이 자동으로 작동합니다.

Android는 두 가지 구현 접근 방식을 모두 보여주는 공식 WebView 패스키 샘플을 제공합니다.

네이티브 패스키 처리가 포함된 최신 WebKit 통합입니다. 이 접근 방식은 사용자 정의 브릿지 코드 없이 네이티브 WebAuthn 지원을 제공합니다.

공식 샘플: Webkit WebView MainActivity

요구 사항:

• AndroidX WebKit 1.12.1 이상 (1.14.0+ 권장)
• Digital Asset Links 구성됨
• WebAuthn 지원이 포함된 WebView APK (기능 감지를 통해 확인)
• 참고: AndroidX Credentials 라이브러리는 완전한 네이티브 구현에만 필요하며 WebView WebAuthn에는 필요하지 않습니다.

구현:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Check if Web Authentication is supported
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Enable Web Authentication
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Enable JavaScript
    webView.settings.javaScriptEnabled = true
}

핵심 사항:

• JavaScript 브릿지 불필요: WebAuthn이 WebView에서 기본적으로 작동합니다.
• 기능 감지 필수: 런타임에 항상 WebViewFeature.WEB_AUTHENTICATION을 확인하세요.
• 조건부 UI 미지원: mediation:"conditional"(입력 필드의 패스키 자동 완성)은 임베디드 WebView에서 작동하지 않습니다.
• 대체 전략: 기능을 사용할 수 없는 경우 Chrome 맞춤 탭을 대신 사용하세요.

버전 참고 사항:

• WebKit 1.12.1 이상을 사용하세요. (1.12.0은 런타임 가용성 문제가 있었습니다.)
• 기능 지원은 사용자의 WebView APK 버전에 따라 다릅니다. 기기의 이전 APK에서는 해당 기능이 노출되지 않습니다.

AndroidX WebKit 1.12.0 이전에는 임베디드 WebView에 네이티브 WebAuthn 지원이 존재하지 않았습니다. 이 기존 접근 방식은 네이티브 WebView WebAuthn을 지원하지 않는 기기의 패스키를 처리하기 위해 Web-to-Native 브릿지를 사용합니다.

공식 샘플:

• PasskeyWebListener (브릿지 핸들러)
• JavaScript 인코딩 유틸리티

사용 시기: 구형 Android 버전 또는 기존 WebView 구현이 있는 기기를 지원할 때.

팀에서는 다음 중 하나를 수행해야 했습니다.

1. Chrome 맞춤 탭 또는 Auth Tab 사용(권장)
2. 사용자 지정 JavaScript 브릿지 구축

자세한 구현 내용은 Android의 자격 증명 관리자 WebView 통합 가이드를 참조하세요. 그러나 최신 앱의 경우 네이티브 WebKit 1.12.1+ 접근 방식을 적극 권장합니다.

권장 사항: AndroidX WebKit 1.12.1+에서 네이티브 WebAuthn 지원을 사용하세요. 런타임에 사용할 수 없는 경우 공유 자격 증명과 함께 훌륭한 패스키 지원을 제공하는 Chrome 맞춤 탭으로 폴백하세요.

네이티브 앱에서 패스키를 구현할 때 앱과 웹 도메인 간의 신뢰를 구축해야 합니다. 이 섹션에서는 단일 도메인, 여러 관련 도메인(ROR)을 처리하는 방법과 잘 알려진 연결 파일이 제대로 구성되었는지 확인하는 방법을 다룹니다.

단일 도메인(예: kayak.com)을 사용하는 앱의 경우 다음이 필요합니다.

• https://kayak.com/.well-known/apple-app-site-association 위치에 iOS용 AASA 파일 1개
• https://kayak.com/.well-known/assetlinks.json 위치에 Android용 assetlinks.json 1개
• webcredentials:kayak.com으로 구성된 Associated Domains 권한

관련 출처(ROR, Related Origins)는 단일 패스키 세트가 여러 관련 도메인(예: kayak.com, kayak.de, kayak.co.uk)에서 작동할 수 있도록 하는 WebAuthn 기능입니다. ROR은 AASA나 assetlinks 파일이 아닌 각 사이트의 /.well-known/webauthn 엔드포인트를 사용하여 관련 출처를 정의합니다.

핵심 사항:

• ROR 구성: 각 도메인은 관련 출처 목록이 포함된 /.well-known/webauthn을 호스팅합니다.
• 앱 연결 파일(AASA/assetlinks): 앱을 해당 웹사이트에 매핑하는 데에만 사용됩니다.
• iOS 18+ 임베디드 WebView: 제대로 구성된 경우 ROR을 지원합니다.
• Associated Domains 권한: 앱이 인증해야 하는 모든 도메인을 포함합니다.

구성 예시:

앱이 kayak.com과 kayak.de 모두에서 작동하는 경우 두 도메인은 다음 조건을 충족해야 합니다.

• 동일한 Team ID와 Bundle ID로 각자의 AASA 파일을 호스팅
• 앱의 Associated Domains 권한에 나열됨
• 적절하게 구성되고 액세스 가능한 잘 알려진 파일을 보유

배포하기 전에 잘 알려진 파일이 제대로 구성되었고 액세스 가능한지 확인하세요. Apple과 Google은 파일 가용성을 확인할 수 있는 CDN 기반 테스트 URL을 제공합니다.

이 테스트 URL 사용하기:

• 링크를 클릭하여 Apple/Google이 잘 알려진 파일을 가져올 수 있는지 확인하세요.
• Apple의 ?nocache=1 매개변수는 CDN 캐시를 우회하여 강제로 최신 버전을 가져옵니다.
• 이 URL을 통해 파일에 액세스할 수 없으면 앱에서 패스키 기능이 작동하지 않습니다.
• 위 URL 패턴의 kayak.com 또는 kayak.de를 자신의 도메인으로 교체하세요.

테스트 시 주의 사항: 모든 도메인이 잘 알려진 파일을 올바르게 구성했는지 확인하세요. 도메인의 파일이 누락되거나 잘못 구성되면 해당 도메인의 패스키 기능이 손상될 수 있습니다.

추가 정보: 네이티브 앱의 WebAuthn RP ID

올바른 구현 접근 방식을 선택하는 것은 앱의 인증 아키텍처, OAuth 요구 사항 및 세션 제어 필요성에 따라 다릅니다. 이 의사 결정 트리를 사용하여 최선의 방법을 결정하세요.

다음 순서도는 앱의 요구 사항에 따라 올바른 구현 접근 방식을 선택하는 과정을 안내합니다.

각 경로에 대한 빠른 참조:

• OAuth 기반 로그인인가요? → 시스템 WebView (ASWebAuthenticationSession / Chrome 맞춤 탭)
• 네이티브 셸에서 웹 인증을 재사용하시나요? → 구성이 있는 임베디드 WebView (WKWebView / Android WebView + WebKit 1.12.1+)
• 네이티브 중심으로 구축하시나요? → 네이티브 구현 (AuthenticationServices / Credential Manager)
• 재사용할 기존 웹 인증이 있나요? → 빠른 구현을 위해 시스템 WebView; 그렇지 않은 경우 최적의 UX를 위해 네이티브 선택

핵심 측면 전반에 걸친 각 접근 방식의 성과는 다음과 같습니다.

항목 설명:

• 패스키 생성: 이 접근 방식을 통해 사용자가 얼마나 쉽게 패스키를 생성할 수 있는지
• 패스키 사용: 기존 패스키를 사용할 때의 인증 경험
• 패스키 관리: 사용자가 패스키를 조회, 수정 또는 삭제하는 방법
• 기술적 복잡성: 개발 노력 및 지속적인 유지보수
• OAuth 지원: 이 접근 방식이 OAuth2/OIDC 인증 흐름을 얼마나 잘 처리하는지
• 설정 기간: 일반적인 구현 소요 시간

권장 사항: 시스템 WebView

앱이 OAuth2, OIDC 또는 소셜 로그인 공급자(Google, GitHub, Microsoft 등)를 통해 인증하는 경우, 시스템 WebView가 최적의 선택입니다.

• iOS: ASWebAuthenticationSession은 OAuth 흐름을 위해 특별히 제작되었습니다.
• Android: Chrome 맞춤 탭은 원활한 OAuth 통합을 제공합니다.
• 장점: 네이티브 코드 최소화, 자격 증명 자동 공유
• 구현: 웹 인증 페이지에 WebAuthn을 추가한 다음, 시스템 WebView를 통해 로드합니다.

예: kayak.com 및 kayak.de와 같은 여행 앱은 인증에 OAuth를 사용합니다. 시스템 WebView를 사용하면 웹 인증 페이지를 통해 패스키 지원을 추가하면서 기존 OAuth 인프라를 유지할 수 있습니다.

권장 사항: 하이브리드 접근 방식

초기 OAuth 인증에는 시스템 WebView를 사용하고, 인증 후 세션에는 임베디드 WebView를 사용합니다.

1. 초기 인증: 시스템 WebView가 OAuth + 패스키 로그인을 처리합니다.
2. 세션 관리: 직접 세션 조작이 필요한 인증된 웹 콘텐츠의 경우 임베디드 WebView로 전환합니다.
3. 기술 설정: 시스템 및 임베디드 WebView 요구 사항을 모두 구성합니다. Android의 경우 AndroidX WebKit 1.12.1+가 포함되어 있는지 확인합니다(섹션 5 참조).

사용 시기: OAuth를 통해 인증하지만, 이후 직접적인 세션 조작이 필요한 인증된 웹 콘텐츠를 표시해야 하는 앱.

권장 사항: 네이티브 구현

처음부터 새로 구축하거나 네이티브 화면이 있나요? 완전한 네이티브로 가세요.

• iOS: AuthenticationServices 프레임워크 사용
• Android: Credential Manager API 사용
• 장점: 최상의 UX, 즉각적인 인증, 완벽한 제어
• 고유한 강점: preferImmediatelyAvailableCredentials를 사용하여 앱 시작 시 자동 패스키 오버레이를 표시하세요. 이는 네이티브 구현에서만 가능하며 가장 높은 전환율을 제공합니다.
• SDK 권장 사항: Corbado SDK(iOS, Android)를 사용하여 프로덕션에서 검증된 엣지 케이스 처리로 개발을 가속화하세요.

새로운 앱의 경우: 첫날부터 네이티브 로그인을 구축하는 것을 강력히 권장합니다. 이는 최적의 UX를 위한 기반을 마련하고 향후 WebView에서 네이티브로 마이그레이션하는 번거로움을 피하게 해 줍니다.

권장 사항: 단계적 마이그레이션

다음 다이어그램은 점진적인 마이그레이션 경로를 보여줍니다.

각 단계는 이전 단계를 기반으로 구축되므로 기존 사용자를 방해하지 않고 점진적인 개선이 가능합니다.

자세한 구성 지침은 섹션 5를 참조하세요.

네이티브 앱에서 패스키를 테스트하려면 체계적이고 다층적인 접근 방식이 필요합니다. 테스트 피라미드를 따르세요: 단위 테스트(분리된 로직), 통합 테스트(시뮬레이터/에뮬레이터에서의 WebAuthn 단계), 시스템 테스트(물리적 기기에서의 End-to-End).

필수 테스트 범주:

• 핵심 여정: 등록, 인증, 기기 간 흐름, 패스키 삭제
• 플랫폼 커버리지: iOS(네이티브), Android(네이티브), OS 버전에 따른 웹 브라우저
• 도메인 연결: AASA 파일(iOS) 및 Digital Asset Links(Android)에 액세스 가능한지 확인
• 취소 흐름: OS 프롬프트 및 생체 인식 화면에서 사용자 취소 테스트
• 오류 처리: 백엔드 실패, 네트워크 시간 초과, 자격 증명 불일치
• 엣지 케이스: 화면 잠금 비활성화, iCloud/Google 비밀번호 관리자 비활성화
• OAuth 흐름: OAuth + 패스키 통합의 End-to-End 완료
• 관리 기기: MDM 통제 환경 (관리 기기 테스트 참조)
• 타사 관리자: 1Password, Bitwarden, Dashlane 호환성
• 기기 간 인증: QR 코드 흐름 및 하이브리드 전송 테스트
• 임베디드 WebView 전용: 임베디드 WebView를 사용하는 경우 Android에서 WebKit 1.12.1+ 구성 확인
• 프로덕션 모니터링: 성공률, 실패 및 지연 시간에 대한 대시보드

자동화 전략, 플랫폼별 주의 사항, 완전한 사전 실행 체크리스트를 포함한 포괄적인 테스트 지침은 네이티브 iOS 및 Android 앱에서 패스키 흐름 테스트 전용 가이드를 참조하세요.

기존 로그인(비밀번호, OAuth)에 성공한 후에 사용자에게 패스키 생성을 유도하는 것을 고려해 보세요. 이 점진적 전환 접근 방식은 다음을 제공합니다.

• 기존 인증 흐름을 방해하지 않습니다.
• 사용자가 거부할 경우 정상적인 작동 저하를 허용합니다.
• 변경을 강요하지 않고 시간이 지남에 따라 패스키 채택률을 높입니다.
• 세 가지 구현 방식 모두와 잘 작동합니다.

예시: 시스템 WebView를 통한 OAuth 로그인 후, "Face ID로 더 빠르게 로그인하시겠습니까?"라는 네이티브 메시지를 표시합니다. 수락하면 시스템 WebView에 로드된 웹 페이지를 통해 패스키를 생성합니다.

패스키를 네이티브 구현, 시스템 WebView 또는 임베디드 WebView 중 어떤 방식으로 구현할지 결정하는 것은 보안, 사용자 경험 및 개발 복잡성에 영향을 미치는 중요한 설계 선택입니다. 모든 상황에 맞는 단일 솔루션은 없습니다.

OAuth 기반 앱의 경우: 시스템 WebView(ASWebAuthenticationSession, Chrome 맞춤 탭)가 권장되는 시작점입니다. 우수한 OAuth 지원을 제공하고, 최소한의 노력으로 구현할 수 있으며, 자동으로 자격 증명을 공유합니다.

네이티브 중심 앱의 경우: 가급적 빨리 네이티브로 가세요. 네이티브 패스키 로그인은 WebView 구현이 제공할 수 없는 기능인 앱 시작 시 자동 패스키 오버레이를 가능하게 하는 preferImmediatelyAvailableCredentials와 같은 독점 기능과 함께 가장 원활한 UX를 제공합니다. iOS와 Android가 패스키에 대한 최고 수준의 지원을 제공함에 따라 실제 성공 사례는 높은 채택률을 보여주고 있습니다. 네이티브 통합을 적절한 기간 내에 달성할 수 있도록 도구(오픈 소스 SDK 및 플랫폼 라이브러리 포함)도 성숙해졌습니다. 기기 관리 정책, 기기 간 동기화, 타사 공급자 등의 문제에 유의해야 하지만, 신중한 엔지니어링과 테스트로 관리할 수 있습니다. 그 결과로 보안을 대폭 향상시키면서도 쉽고 빠른 인앱 로그인으로 사용자에게 기쁨을 줍니다.

임베디드 WebView 프레임 요구 사항이 있는 경우: 임베디드 WebView는 두 가지 실제 시나리오에서 자주 사용됩니다. 첫째, OAuth 기반 앱은 초기 로그인 흐름에 시스템 WebView를 사용한 다음, 세션 제어가 필요한 설정 화면에서 패스키 관리 옵션을 렌더링하기 위해 임베디드 WebView로 전환하는 경우가 많습니다. 물론 일부 앱은 이 두 흐름을 모두 시스템 WebView로 단순하게 유지합니다. 둘째, 패스키를 도입하기 전에 이미 인증 흐름을 WebView 프레임에 내장한 앱은 일관성을 위해 이 패턴을 계속 사용합니다. 네이티브 WebAuthn 지원이 포함된 임베디드 WebView(AndroidX WebKit 1.12.1+)는 구성 및 설정(권한, 자격 증명, WebView 설정)이 필요하지만, 더 이상 사용자 지정 JavaScript 브릿지 코드가 필요하지 않습니다. 조건부 UI는 임베디드 WebView에서 지원되지 않습니다. 기존 임베디드 인증 패턴을 유지하거나 인증 후 화면을 위한 세션/쿠키 제어가 필요할 때 이 접근 방식을 선택하세요.

궁극적으로 네이티브 앱의 패스키는 사용자 편의성과 보안 측면에서 엄청난 발전을 의미합니다. 네이티브, 시스템 WebView, 임베디드 WebView 등 어떤 방식을 통해 구현하든 패스키는 사용자의 피싱 위험과 비밀번호 관리 부담을 없애 줍니다. VicRoads의 네이티브 앱 패스키 통합과 같은 실제 구현 사례는 네이티브 중심 접근 방식이 자동 패스키 오버레이와 같은 기능과 함께 적절히 실행될 때 사용자 채택과 만족도가 가장 높음을 보여줍니다. 사용자 친화적인 인증을 위한 모범 사례를 따르고 앱의 아키텍처(새로운 앱을 위한 네이티브 중심, OAuth 흐름을 위한 시스템 WebView, 또는 기존 임베디드 패턴을 위한 임베디드 WebView)에 맞는 구현 방식을 선택하면, 모든 사람을 위한 간단하고 안전하며 즐거운 인증이라는 패스키의 비전을 진정으로 실현하는 비밀번호 없는 생체 로그인을 제공할 수 있습니다.

네이티브 앱에서 패스키가 작동하지 않는 경우 구현 방식에 따라 다음과 같은 일반적인 문제를 확인하세요.

• 유효한 인증서가 있는 HTTPS를 통해 제공된 파일
• 올바른 MIME 유형: application/json
• .well-known 경로에 리디렉션 없음
• iOS: Team ID와 Bundle ID가 AASA 파일에 정확히 일치함
• Android: SHA256 지문이 assetlinks.json의 서명 인증서와 일치함
• Relying Party ID가 도메인과 일치함(프로토콜 및 포트 없음)
• RP ID에 후행 슬래시가 없음
• WebAuthn 출처: https://your-domain.com (app:// 아님)

• iOS: Xcode에서 webcredentials:yourdomain.com으로 Associated Domains 기능 활성화
• Android: AndroidManifest.xml에 Digital Asset Links 선언
• 사용자가 화면 잠금(생체 인식 또는 PIN) 활성화
• Apple의 AASA Validator 및 Google의 Digital Asset Links 도구로 테스트
• Runner.entitlements 파일에 올바른 Associated Domains가 포함되어 있는지 확인

• iOS: ASWebAuthenticationSession(권장) 또는 SFSafariViewController 사용
• Android: Chrome 맞춤 탭 사용(일반 WebView 아님)
• iOS: 필요한 경우 Associated Domains가 구성되어 있는지 확인
• 쿠키/자격 증명이 시스템 브라우저와 공유되는지 테스트
• 웹 인증 페이지에 적절한 WebAuthn이 구현되어 있는지 확인

• iOS: 적절한 권한(entitlements)으로 구성됨
• iOS: 관련 도메인에 관련된 모든 도메인이 포함됨
• iOS: AASA 파일 액세스 가능 및 올바르게 형식 지정
• iOS: 개발 중 ?mode=developer로 테스트(프로덕션에서는 제거)
• Android: 프로젝트에 AndroidX WebKit 1.12.1+(또는 최신)가 포함됨
• Android: WebViewFeature.WEB_AUTHENTICATION에 대한 런타임 기능 확인
• Android: WEB_AUTHENTICATION_SUPPORT_FOR_APP과 함께 setWebAuthenticationSupport() 호출
• Android: WebView 설정에서 JavaScript 활성화됨
• Android: 사용자의 WebView APK 버전이 WebAuthn 기능을 지원함(OS 버전이 아닌 기능 감지 사용)
• 조건부 UI 미사용(임베디드 WebView에서 미지원)
• WebAuthn 기능을 사용할 수 없는 경우 Chrome 맞춤 탭으로 폴백

• 사용자가 기본이 아닌 자격 증명 공급자를 활성화했는지 확인 (1Password, Bitwarden 등)
• 공급자가 패스키를 지원하는지 확인 (모든 비밀번호 관리자가 지원하는 것은 아님)
• 플랫폼 네이티브 자격 증명 관리자로 테스트 (iCloud 키체인, Google 비밀번호 관리자)

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• 의미: 누락된 권한(iOS) 또는 WebView 기능을 사용할 수 없거나 비활성화됨(Android 임베디드 WebView)
• 확인: Associated Domains 구성, AASA 파일 액세스 가능 여부, WebKit 버전, 기능 감지, setWebAuthenticationSupport() 호출

패스키 메시지가 표시되지 않음

• 의미: AASA/assetlinks.json 미로드, 잘못된 WebView 유형, AASA 파일 캐싱
• 조치: 연결 파일 검증, 테스트를 위해 iOS에서 ?mode=developer 사용, WebView 유형 확인

세부적인 디버깅에 대해서는 네이티브 앱의 RP ID에 관한 기사를 참조하세요.

흔히 하는 실수: 제한된 액세스(IP 화이트리스트, VPN 전용)를 사용하는 스테이징 환경은 실패하게 됩니다. Apple 및 Google CDN은 연결 파일을 가져올 수 있어야 합니다.

• AASA/assetlinks 파일은 공개적으로 접근 가능해야 합니다 (IP 화이트리스트 금지, VPN 요구 금지)
• Apple CDN이 파일에 도달할 수 있는지 확인: https://app-site-association.cdn-apple.com/a/v1/your-staging-domain.com?nocache=1
• Google이 파일에 도달할 수 있는지 확인: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://your-staging-domain.com&relation=delegate_permission/common.handle_all_urls

프로덕션 rpID를 사용하는 스테이징 하위 도메인:

스테이징 환경(예: stg.login.example.com)이 프로덕션 도메인을 rpID(예: example.com)로 사용하는 경우 AASA 조회는 스테이징 하위 도메인이 아닌 rpID 도메인에서 발생합니다. 의미:

• 스테이징 앱의 Bundle ID를 프로덕션 AASA 파일에 추가해야 합니다.
• 스테이징 환경에서 생성된 패스키는 프로덕션 로그인 흐름에 나타납니다. (혼란의 가능성 인지)

예 (하나의 AASA를 공유하는 여러 환경):

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

권장 사항: 스테이징 도메인과 일치하는 별도의 스테이징 rpID를 사용하여 환경 간 자격 증명 중첩을 방지하세요. 이를 위해서는 스테이징 도메인에서 대중이 접근 가능한 AASA 파일이 필요합니다.

?mode=developer 관련 설명:

Associated Domains의 ?mode=developer 매개변수는 Apple의 CDN 캐시를 우회하지만 접근 가능 요구 사항을 우회하는 것은 아닙니다. AASA 파일은 여전히 기기에서 접근할 수 있어야 합니다(Apple의 CDN을 통해서가 아니라 직접). 이는 AASA 변경 사항을 적용할 때 개발 중에는 도움이 되지만 스테이징 서버가 IP 화이트리스트에 있는 경우에는 도움이 되지 않습니다.

Corbado 네이티브 SDK:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Flutter Package

플랫폼 공식 문서:

• Apple: 패스키 지원
• Google: Credential Manager

검증 도구:

• Apple AASA Validator
• Google Digital Asset Links Generator

Corbado 소개

Corbado는 대규모로 consumer authentication을 운영하는 CIAM 팀을 위한 Passkey Intelligence Platform입니다. IDP 로그와 일반 analytics 도구가 보여주지 못하는 것을 볼 수 있게 해드립니다: 어떤 디바이스, OS 버전, 브라우저, credential manager가 passkey를 지원하는지, 왜 등록이 로그인으로 이어지지 않는지, WebAuthn 플로우가 어디서 실패하는지, OS나 브라우저 업데이트가 언제 조용히 로그인을 망가뜨리는지 — Okta, Auth0, Ping, Cognito 또는 자체 IDP를 교체하지 않고도 전부 파악할 수 있습니다. 두 가지 제품: Corbado Observe는 passkey 및 다른 모든 로그인 방식에 대한 observability를 더합니다. Corbado Connect는 analytics가 내장된 managed passkey를 제공합니다 (기존 IDP와 함께). VicRoads는 Corbado로 500만+ 사용자에게 passkey를 운영하고 있습니다 (passkey 활성화율 +80%). Passkey 전문가와 상담하기 →

선택은 앱의 인증 아키텍처에 따라 달라집니다. 앱이 OAuth2 또는 OIDC를 사용하는 경우 시스템 WebView(iOS의 ASWebAuthenticationSession 또는 Android의 Chrome 맞춤 탭)는 구현 노력이 가장 적게 들고 연결 파일 설정이 필요 없습니다. 새로운 네이티브 중심 앱의 경우 네이티브 구현이 우수한 UX를 제공하며, 임베디드 WebView는 인증을 WebView 프레임에 이미 내장했고 로그인 후 세션 또는 쿠키 제어가 필요한 앱에 적합합니다.

SFSafariViewController는 Safari 엔진을 활용하고 SSL 표시기와 함께 URL 표시줄을 보여주며 피싱 보호를 제공하므로 인증 흐름에서 신뢰도를 높여줍니다. WKWebView는 더 많은 UI 사용자 지정 기능을 제공하지만 Safari와 분리된 쿠키 저장소를 갖고 있고, 패스키를 활성화하기 위해 Associated Domains 권한과 AASA 파일이 필요하며 URL 표시줄을 표시하지 않아 사용자의 신뢰 신호를 감소시킵니다.

Chrome 맞춤 탭은 사용자의 Chrome 브라우저와 쿠키 및 저장된 자격 증명을 공유합니다. 즉, 인증 과정 중 Google 비밀번호 관리자에 저장된 패스키에 접근할 수 있습니다. 반면 표준 Android WebView는 독립된 쿠키 저장소를 가지고 URL이나 SSL 표시기를 보여주지 않으며 피싱 위험으로 인해 Google이 Google 계정 로그인에 사용하지 못하도록 명시적으로 금지했습니다.

사용자가 1Password와 같은 타사 자격 증명 관리자를 활성 공급자로 설정한 경우 이 공급자가 패스키의 생성 및 저장을 가로채며 플랫폼의 기본 자격 증명 관리자(iCloud 키체인 또는 Google 비밀번호 관리자)보다 우선순위를 갖는 경우가 많습니다. 즉 패스키가 플랫폼 키체인 대신 타사 앱에 저장되어 기기 간 동기화와 패스키 관리 동작에 영향을 줄 수 있습니다.

MDM 정책이 자격 증명 동기화를 비활성화하면 일반적인 소비자 상황과 달리 패스키가 기기에 묶이게 되며 새 기기로 이동할 수 없게 됩니다. 기업 환경을 타겟팅하는 앱은 사용자가 새로운 관리 기기를 받을 경우를 대비해 비밀번호나 매직 링크 로그인과 같은 대체 인증 메커니즘을 계획해야 합니다.