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

+70-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

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

주요 결정 요인:

• OAuth 기반 로그인인가요? → 시스템 웹뷰 (ASWebAuthenticationSession, Chrome 맞춤 탭)
• 웹 인증을 네이티브 셸에서 재사용하고 싶나요? → 임베디드 웹뷰 (WKWebView, WebKit 1.12.1+를 사용하는 Android 웹뷰)
• 네이티브 우선 앱을 구축하고 있나요? → 네이티브 구현 (Apple AuthenticationServices, Google Credential Manager)

최신 모바일 플랫폼은 네이티브 앱에 패스키를 통합하기 위한 세 가지 뚜렷한 접근 방식을 제공합니다. 각 방식은 사용자 경험, 기술적 복잡성, OAuth 호환성 측면에서 서로 다른 장단점을 가집니다.

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

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

3. 임베디드 웹뷰: 네이티브 앱 스켈레톤으로 웹 인증을 재사용하기 위해 앱 내에 사용자 정의 가능한 웹뷰(iOS WKWebView, Android WebView)를 내장합니다. URL 표시줄 없이 네이티브와 유사한 외관을 제공하며 웹뷰 UI를 완전히 제어할 수 있습니다. 패스키 기능을 활성화하려면 권한 및 자격(iOS), AndroidX WebKit 1.12.1+를 사용한 웹뷰 구성(Android) 등 추가 설정이 필요합니다.

올바른 선택은 앱의 인증 아키텍처, OAuth 제공업체 사용 여부, UI 제어 수준, 네이티브 우선으로 구축하는지 또는 웹 구성 요소를 재사용하는지에 따라 달라집니다.

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

네이티브 구현을 선택해야 할 때:

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

핵심 장점: preferImmediatelyAvailableCredentials()

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

웹뷰 구현은 Conditional UI(입력 필드의 패스키 제안)를 사용할 수 있지만, 네이티브의 자동 오버레이는 앱 실행 즉시 인증이 시작되므로 더 높은 패스키 사용률과 우수한 UX를 제공합니다.

기술 요구사항 개요:

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

1. /.well-known/에 호스팅된 앱-도메인 연결 파일
2. 웹 도메인과 일치하는 올바른 Relying Party ID
3. 플랫폼별 기능(섹션 4에서 자세히 설명)

가장 큰 이점은 웹사이트에서 생성된 패스키가 앱에서 원활하게 작동하고 그 반대도 가능하다는 것입니다.

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

주요 구성 요소:

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

개발 팁

• AASA 캐싱: Apple은 AASA 파일을 공격적으로 캐시(최대 24시간)하여 테스트를 어렵게 만들 수 있습니다. 해결책: 테스트 기기에서 개발자 모드를 활성화하고 AASA URL에 ?mode=developer를 추가하여 강제로 새 파일을 가져옵니다.
• 성능 테스트: 수백 개의 자격 증명이 포함된 iCloud 계정으로 테스트하여 실제 지연 시간을 관찰합니다. 많은 패스키가 저장되어 있으면 시스템 오버레이가 약간의 지연을 보일 수 있습니다.

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

주요 구성 요소:

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

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

패스키를 네이티브로 구현하는 데에는 중요한 과제와 교훈이 있습니다. OS 수준에서 통합하면 다양한 기기 및 OS 버전에서 문제가 발생할 수 있습니다.

1. 예를 들어, 우리 팀은 Apple의 apple-app-site-association 파일(앱/웹 자격 증명 연결에 사용)의 공격적인 캐싱 문제와 특정 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

Corbado proved to be a trusted partner. Their hands-on, 24/7 support and on-site assistance enabled a seamless integration into VicRoads' complex systems, offering passkeys to 5 million users.

수백만 명이 빠르게 채택하는 Passkeys. Corbado의 Adoption Platform으로 시작하세요.

무료 평가판 시작하기

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

시스템 웹뷰를 선택해야 할 때:

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

주요 장점:

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

플랫폼 구성 요소:

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

Google 및 GitHub과 같은 주요 기업들은 기존 웹 인증 페이지에 웹뷰 오버레이를 통해 모바일 앱에 패스키 로그인을 추가하기 위해 이 접근 방식을 채택했습니다. 이는 완전한 네이티브 인증 재구축이 즉시 실현 가능하지 않을 때 잘 작동합니다.

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

ASWebAuthenticationSession (인증에 권장):

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

SFSafariViewController (일반 브라우징):

• 앱 내에서 전체 Safari 경험을 제공함
• URL 표시줄과 보안 표시기를 보여줌
• iOS 11 이상에서는 Safari 쿠키를 공유하지 않음. Safari 세션 공유가 필요한 경우 ASWebAuthenticationSession을 사용하세요.
• 사용자 정의 기능은 적지만 사용자에게 더 신뢰를 줌

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

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

주요 기능:

• Chrome 브라우저와 쿠키 및 자격 증명을 공유함
• URL 및 보안 표시기를 보여줌
• 툴바 색상 및 브랜딩을 사용자 정의할 수 있음
• 더 빠른 로드 시간을 위한 사전 워밍업

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

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

임베디드 웹뷰는 앱 내에서 웹 콘텐츠 렌더링을 완벽하게 제어할 수 있게 해주어 URL 표시줄 없이 쿠키, 세션, 탐색을 직접 조작할 수 있습니다. 그러나 이러한 제어에는 패스키 기능을 활성화하기 위한 추가적인 기술 요구사항이 따릅니다.

임베디드 웹뷰를 선택해야 할 때:

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

중요한 맥락:

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

기술 요구사항:

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

1. iOS: 연결된 도메인(Associated Domains) 자격, AASA 파일 구성
2. Android: WebView WebAuthn 구성을 포함한 AndroidX WebKit 1.12.1+ (기능 감지 필요)
3. 둘 다: 올바르게 구성된 well-known 연결 파일 및 디지털 자산 링크(Digital Asset Links)

플랫폼 구성 요소:

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

장단점:

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

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

iOS에서는 앱 내에서 웹 콘텐츠를 표시하기 위한 여러 옵션이 있습니다.

• WKWebView는 WebKit 프레임워크의 일부인 사용자 정의 가능한 웹뷰입니다(iOS 8에서 도입). 웹 콘텐츠의 모양과 동작을 많이 제어할 수 있습니다.
• SFSafariViewController는 Apple에서 제공하는 뷰 컨트롤러로, 앱 내에서 경량 Safari 브라우저 역할을 합니다. Safari의 엔진을 사용합니다. iOS 11 이상에서는 별도의 쿠키 저장소를 가지고 있으며 Safari 쿠키를 공유하지 않습니다. Safari 세션 공유가 필요한 경우 ASWebAuthenticationSession을 사용하세요.
• SFAuthenticationSession / ASWebAuthenticationSession은 OAuth/OpenID 또는 기타 보안 로그인 흐름을 위해 특별히 고안된 전문 웹 인증 세션입니다(iOS 11/12부터 사용 가능). 이들도 내부적으로 Safari를 활용하지만, 인증 흐름에 중점을 두고 공유 쿠키 및 싱글 사인온(SSO)과 같은 것을 자동으로 처리합니다.

Android의 주요 선택지는 다음과 같습니다.

• Android WebView는 표준 웹뷰 위젯(android.webkit.WebView)으로, 본질적으로 액티비티에 내장할 수 있는 미니 브라우저입니다. 사용자 정의가 매우 용이하지만 앱의 프로세스 내에서 실행됩니다.
• **Chrome 맞춤 탭(CCT)**은 앱 컨텍스트 내에서 Chrome 기반 탭을 여는 기능입니다. 맞춤 탭은 앱의 일부처럼 보이지만 (설치된 경우) Chrome 브라우저에 의해 구동되며, 사전 로딩, 공유 쿠키, 친숙한 URL 표시줄과 같은 기능을 제공하여 사용자 신뢰를 높입니다.

다음 섹션에서는 iOS 및 Android용 웹뷰 유형에 대해 더 자세히 알아보고, 패스키 인증 흐름에 어떤 것이 가장 적합할지 논의하겠습니다.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Apple의 플랫폼은 위에 나열된 세 가지 웹뷰 옵션을 제공합니다. 어떤 것을 선택하느냐에 따라 앱 내에서 패스키를 얼마나 원활하게 사용할 수 있는지가 달라집니다.

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

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

SFSafariViewController는 인앱 Safari 경험을 제공합니다. SFSafariViewController로 URL을 열면 사용자가 앱의 UI 내에 머무른다는 점을 제외하고는 실제 Safari 브라우저에서 여는 것과 거의 같습니다. 패스키에 대한 이점은 상당합니다. 본질적으로 Safari이기 때문에 사용자의 iCloud 키체인과 저장된 패스키에 접근할 수 있습니다. iOS 11 이상에서는 쿠키가 공유되지 않는다는 점에 유의하세요. 즉, 사용자가 이미 사이트에 대한 패스키를 가지고 있다면 Safari가 이를 찾아 Conditional UI 자동 완성을 표시하여 쉽게 로그인할 수 있습니다. SFSafariViewController는 사용자 정의가 덜 가능하지만(툴바를 많이 변경할 수 없음), 많은 보안 및 개인 정보 보호 기능을 자동으로 처리합니다. HTTPS용 자물쇠 아이콘과 함께 URL 표시줄이 표시되어 사용자가 올바른 도메인에 있다는 확신을 줍니다. 일반적으로 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에서 웹뷰 접근 방식을 선택하는 경우, ASWebAuthenticationSession은 안전하고 Safari와 상태를 공유하며 인증을 위해 특별히 제작되었기 때문에 패스키를 구현하는 데 일반적으로 최상의 선택입니다.

Want to find out how many people use passkeys?

View Adoption Data

Android에서 웹뷰 결정은 클래식 웹뷰와 Chrome 맞춤 탭 사이에서 이루어집니다.

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

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

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

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

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

어떤 구현 방식을 선택하든 패스키 기능을 활성화하려면 특정 기술 요구사항을 충족해야 합니다. 이 섹션에서는 well-known 연결 파일, iOS 자격, Android 웹뷰 구성에 대한 포괄적인 지침을 제공합니다.

관리형 기기 참고: 패스키 동작은 모바일 기기 관리(MDM) 정책이 자격 증명 저장을 제어하는 관리형 기기에서 크게 변경됩니다. 관리형 기기에서 패스키를 테스트하려면 관리형 iOS 및 Android 기기에서의 패스키를 참조하세요.

네이티브 및 임베디드 웹뷰 흐름은 앱과 웹 도메인 간의 암호화 신뢰를 설정하기 위해 연결 파일이 필요합니다. 시스템 웹뷰(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 경로에 리디렉션 없음
• 앱의 팀 ID 및 번들 ID 포함

AASA 파일 예시:

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

AASA 캐싱 및 테스트:

Apple은 CDN을 사용하여 AASA 파일을 공격적으로 캐시(최대 24-48시간)하므로 개발 및 테스트를 어렵게 만듭니다. 개발 중 캐싱을 우회하려면:

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

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

유효성 검사: Apple의 AASA 유효성 검사기를 사용하여 구성을 확인하세요.

Android는 디지털 자산 링크를 사용하여 앱과 웹사이트 간의 관계를 확인합니다.

파일 위치: 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의 디지털 자산 링크 생성기를 사용하여 구성을 생성하고 확인하세요.

iOS 앱은 패스키 기능에 접근하기 위해 적절한 자격이 필요합니다. 요구사항은 구현 방식에 따라 약간 다릅니다.

자격 파일(종종 Flutter 앱에서는 Runner.entitlements, 네이티브 iOS 프로젝트에서는 YourApp.entitlements라고 함)은 Apple 시스템에서 부여하는 특별한 권한과 기능을 정의합니다. 패스키의 경우 이 파일은 연결된 도메인을 구성합니다.

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

네이티브 구현 및 임베디드 웹뷰는 앱을 웹 도메인과 연결하기 위해 연결된 도메인 기능이 필요합니다. 시스템 웹뷰(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)이 필요할 수 있습니다.

Android 임베디드 웹뷰는 AndroidX WebKit 1.12와 함께 네이티브 WebAuthn 지원을 받게 되어 사용자 정의 JavaScript 브리지 코드의 필요성을 없앴습니다. 시스템 웹뷰(Chrome 맞춤 탭)는 구성이 필요 없으며 자격 증명이 자동으로 작동합니다.

요구사항:

• AndroidX WebKit 1.12.1 이상 (1.14.0+ 권장)
• 디지털 자산 링크 구성됨
• WebAuthn을 지원하는 WebView APK (기능 감지를 통해 확인)
• 참고: AndroidX Credentials 라이브러리는 WebView WebAuthn에 필요하지 않으며, 완전한 네이티브 구현에만 필요합니다.

구현:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// 웹 인증이 지원되는지 확인
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // 웹 인증 활성화
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // JavaScript 활성화
    webView.settings.javaScriptEnabled = true
}

핵심 사항:

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

버전 참고:

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

AndroidX WebKit 1.12.0 이전에는 임베디드 웹뷰에 네이티브 WebAuthn 지원이 없었습니다. 팀은 다음 중 하나를 해야 했습니다.

1. Chrome 맞춤 탭 또는 인증 탭 사용(권장)
2. 사용자 정의 JavaScript 브리지 구축

오래된 Android 버전이나 업데이트된 WebView APK가 없는 기기를 지원해야 하는 경우, 브리지 코드 접근 방식에 대한 Android의 Credential Manager WebView 통합 가이드를 참조하세요. 그러나 최신 앱에는 네이티브 WebKit 1.12.1+ 접근 방식을 사용하는 것을 강력히 권장합니다.

권장 사항: AndroidX WebKit 1.12.1+와 함께 네이티브 WebAuthn 지원을 사용하세요. 런타임에 사용할 수 없는 경우, 공유 자격 증명과 함께 뛰어난 패스키 지원을 제공하는 Chrome 맞춤 탭으로 대체하세요.

네이티브 앱에서 패스키를 구현할 때 앱과 웹 도메인 간의 신뢰를 설정해야 합니다. 이 섹션에서는 단일 도메인, 여러 관련 도메인(ROR)을 처리하는 방법과 well-known 연결 파일이 올바르게 구성되었는지 확인하는 방법을 다룹니다.

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

• iOS용 AASA 파일 1개: https://kayak.com/.well-known/apple-app-site-association
• Android용 assetlinks.json 1개: https://kayak.com/.well-known/assetlinks.json
• webcredentials:kayak.com으로 구성된 연결된 도메인 자격

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

핵심 사항:

• ROR 구성: 각 도메인은 관련 출처 목록과 함께 /.well-known/webauthn을 호스팅합니다.
• 앱 연결 파일(AASA/assetlinks): 앱을 해당 웹사이트에 매핑하는 데만 사용됩니다.
• iOS 18+ 임베디드 웹뷰: 올바르게 구성되면 ROR을 지원합니다.
• 연결된 도메인 자격: 앱이 인증해야 하는 모든 도메인을 포함합니다.

구성 예시:

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

• 동일한 팀 ID와 번들 ID로 각자의 AASA 파일을 호스팅
• 앱의 연결된 도메인 자격에 나열됨
• 올바르게 구성되고 접근 가능한 well-known 파일 보유

라이브로 전환하기 전에 well-known 파일이 올바르게 구성되고 접근 가능한지 확인하세요. Apple과 Google은 파일 가용성을 확인하기 위해 CDN 기반 테스트 URL을 제공합니다.

이 테스트 URL 사용법:

• 링크를 클릭하여 Apple/Google이 well-known 파일을 검색할 수 있는지 확인합니다.
• Apple의 ?nocache=1 매개변수는 CDN 캐시를 우회하여 강제로 새로 검색합니다.
• 이 URL을 통해 파일에 접근할 수 없는 경우, 앱에서 패스키 기능이 작동하지 않습니다.
• 위의 URL 패턴에서 kayak.com 또는 kayak.de를 자신의 도메인으로 교체합니다.

테스트 시 주의사항: 모든 도메인에 well-known 파일이 올바르게 구성되었는지 확인하세요. 특정 도메인에 파일이 없거나 잘못 구성된 경우 해당 도메인의 패스키 기능이 손상될 수 있습니다.

추가 정보: 네이티브 앱에서의 WebAuthn Relying Party ID

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

다음 주요 질문으로 시작하세요.

1. 앱이 OAuth 기반 로그인(OAuth2, OIDC, 소셜 로그인 제공업체)을 사용하나요?

   • 예 → 시스템 웹뷰 (섹션 1.2)
     • iOS: ASWebAuthenticationSession 사용
     • Android: Chrome 맞춤 탭 사용
     • 공유 자격 증명으로 뛰어난 OAuth 지원

2. 네이티브와 유사한 셸(URL 표시줄 없음, 전체 UI 제어)에서 웹 인증을 재사용하고 싶으신가요?

   • 예 → 구성이 포함된 임베디드 웹뷰 (섹션 1.3)
   • iOS: WKWebView + 연결된 도메인 자격
   • Android: WebView + AndroidX WebKit 1.12.1+ 구성
   • 웹 구성 요소를 재사용하면서 네이티브와 유사한 외관 제공
   • 참고: 임베디드 웹뷰에서는 Conditional UI가 지원되지 않음
   • 아니요 → 시스템 웹뷰 또는 네이티브 고려

3. 새로운 네이티브 앱을 구축 중이거나 네이티브 로그인 화면이 있나요?

   • 예 → 네이티브 구현 (섹션 1.1)
     • 최고의 사용자 경험
     • 즉각적이고 조용한 인증
     • 플랫폼별 개발 필요

4. 재사용하고 싶은 기존 웹 인증이 있나요?

   • 예 → 빠른 구현을 위한 시스템 웹뷰
   • 아니요 → 최적의 UX를 위한 네이티브 구현

각 접근 방식이 주요 차원에서 어떻게 수행되는지는 다음과 같습니다.

차원 설명:

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

권장: 시스템 웹뷰

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

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

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

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

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

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

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

권장: 네이티브 구현

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

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

새로운 앱의 경우: 처음부터 네이티브 로그인을 구축하는 것을 강력히 권장합니다. 최적의 UX를 위한 기반을 마련하고 향후 웹뷰에서 네이티브로의 마이그레이션을 피할 수 있습니다.

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

• 1단계: 시스템 웹뷰 패스키 - 기존 웹 로그인에 패스키 지원을 추가하고, 시스템 웹뷰(ASWebAuthenticationSession/Chrome 맞춤 탭)를 통해 로드합니다. 최소한의 네이티브 코드로 빠른 성과를 거둘 수 있습니다.
• 2단계: 네이티브 가로채기 - 웹뷰를 표시하기 전에 네이티브 패스키 확인을 추가합니다. 예: kayak.com은 먼저 네이티브 패스키 인증을 시도하고, 필요한 경우 웹뷰로 대체합니다. 이전 버전과의 호환성을 유지하면서 빠른 생체 인증 로그인을 제공합니다.
• 3단계: 완전 네이티브 - 레거시 방법은 웹뷰를 유지하면서 패스키 사용자를 위해 점차적으로 네이티브 인증으로 마이그레이션합니다.

이 단계적 접근 방식은 기존 사용자를 방해하지 않으면서 점진적인 개선을 가능하게 합니다.

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

네이티브 앱에서 패스키를 테스트하려면 구조화된 다계층 접근 방식이 필요합니다. 테스트 피라미드를 따르세요: 단위 테스트(격리된 로직), 통합 테스트(시뮬레이터/에뮬레이터에서의 WebAuthn 절차), 시스템 테스트(실제 기기에서의 엔드투엔드 테스트).

필수 테스트 카테고리:

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

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

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

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

예시: 시스템 웹뷰를 통해 OAuth 로그인 후 네이티브 프롬프트를 표시합니다: "Face ID로 더 빠른 로그인을 활성화하시겠습니까?" 수락하면 시스템 웹뷰에 로드된 웹 페이지를 통해 패스키를 생성합니다.

네이티브 구현, 시스템 웹뷰 또는 임베디드 웹뷰를 통해 패스키를 구현하는 방법을 결정하는 것은 보안, 사용자 경험 및 개발 복잡성에 영향을 미치는 중요한 설계 선택입니다. 모든 경우에 적용되는 정답은 없습니다.

OAuth 기반 앱의 경우: 시스템 웹뷰(ASWebAuthenticationSession, Chrome 맞춤 탭)가 권장되는 시작점입니다. 뛰어난 OAuth 지원, 최소한의 구현 노력 및 자동 자격 증명 공유를 제공합니다.

네이티브 우선 앱의 경우: 가능한 한 빨리 네이티브로 전환하세요. 네이티브 패스키 로그인은 preferImmediatelyAvailableCredentials와 같은 독점적인 기능으로 가장 원활한 UX를 제공하며, 이는 웹뷰 구현에서는 제공할 수 없는 앱 시작 시 자동 패스키 오버레이를 가능하게 합니다. iOS와 Android가 이제 패스키에 대한 일류 지원을 제공함에 따라 실제 성공 사례는 높은 채택률을 보여줍니다. 도구(오픈 소스 SDK 및 플랫폼 라이브러리 포함)는 합리적인 시간 내에 네이티브 통합을 달성할 수 있도록 성숙해졌습니다. 기기 관리 정책, 교차 기기 동기화 및 서드파티 제공업체에 유의해야 하지만, 이러한 과제는 신중한 엔지니어링과 테스트를 통해 관리할 수 있습니다. 그 결과는 사용자의 편의성과 속도로 사용자를 기쁘게 하면서 보안을 크게 향상시키는 앱 로그인입니다.

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

궁극적으로 네이티브 앱의 패스키는 사용자 편의성과 보안 모두에서 큰 도약을 의미합니다. 네이티브, 시스템 웹뷰 또는 임베디드 웹뷰를 통해 구현되든, 피싱 위험과 사용자의 비밀번호 관리 부담을 없애줍니다. VicRoads의 네이티브 앱 패스키 통합과 같은 실제 구현 사례는 네이티브 우선 접근 방식이 자동 패스키 오버레이와 같은 기능으로 올바르게 실행될 때 가장 높은 사용자 채택률과 만족도를 제공한다는 것을 보여줍니다. 사용자 친화적인 인증을 위한 모범 사례를 따르고 앱 아키텍처에 맞는 구현 접근 방식(새로운 앱의 경우 네이티브 우선, OAuth 흐름의 경우 시스템 웹뷰, 기존 내장 패턴의 경우 임베디드 웹뷰)을 선택하면, 패스키의 비전인 모두를 위한 간단하고 안전하며 즐거운 인증을 실현하는 비밀번호 없는 생체 인증 로그인을 제공할 수 있습니다.

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

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

• iOS: Xcode에서 webcredentials:yourdomain.com으로 연결된 도메인 기능 활성화
• Android: AndroidManifest.xml에 디지털 자산 링크 선언
• 사용자가 화면 잠금(생체 인식 또는 PIN) 활성화
• Apple의 AASA 유효성 검사기 및 Google의 디지털 자산 링크 도구로 테스트
• Runner.entitlements 파일에 올바른 연결된 도메인이 포함되어 있는지 확인

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

• iOS: 적절한 자격으로 구성됨
• iOS: 연결된 도메인에 모든 관련 도메인 포함
• iOS: AASA 파일 접근 가능하고 올바르게 포맷됨
• iOS: 개발 중 ?mode=developer로 테스트 (프로덕션용으로는 제거)
• Android: 프로젝트에 AndroidX WebKit 1.12.1+ (또는 최신) 포함
• Android: WebViewFeature.WEB_AUTHENTICATION에 대한 런타임 기능 확인
• Android: setWebAuthenticationSupport()가 WEB_AUTHENTICATION_SUPPORT_FOR_APP으로 호출됨
• Android: 웹뷰 설정에서 JavaScript 활성화
• Android: 사용자의 웹뷰 APK 버전이 WebAuthn 기능 지원 (OS 버전이 아닌 기능 감지 사용)
• Conditional UI 사용 안 함 (임베디드 웹뷰에서 지원되지 않음)
• WebAuthn 기능을 사용할 수 없는 경우 Chrome 맞춤 탭으로 대체

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

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

• 일반적인 의미: 자격 증명 누락(iOS) 또는 웹뷰 기능 사용 불가/비활성화(Android 임베디드 웹뷰)
• 확인 사항: 연결된 도메인 구성, AASA 파일 접근성, WebKit 버전, 기능 감지, setWebAuthenticationSupport() 호출

패스키 프롬프트가 나타나지 않음

• 의미 가능성: AASA/assetlinks.json 로드 실패, 잘못된 웹뷰 유형, 캐시된 AASA 파일
• 시도해 볼 것: 연결 파일 유효성 검사, 테스트를 위해 iOS에서 ?mode=developer 사용, 웹뷰 유형 확인

자세한 디버깅은 네이티브 앱의 Relying Party ID에 대한 기사를 참조하세요.

Corbado 네이티브 SDK:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Flutter 패키지

플랫폼 문서:

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

유효성 검사 도구:

• Apple AASA 유효성 검사기
• Google 디지털 자산 링크 생성기