Android 앱에 적합한 패스키 구현 선택

패스키는 안전하고 사용자 친화적인 인증의 표준이 되었으며, 점점 더 많은 서비스가 웹사이트와 Android 앱 모두에서 패스키를 채택하고 있습니다. 하지만 Android 앱에 패스키를 추가하기 시작하면 네이티브 API를 직접 호출할지, 브라우저 탭에서 기존 웹 로그인 페이지를 열지, 인앱 WebView 내에서 패스키를 실행할지와 같은 주요 아키텍처 질문에 직면하는 경우가 많습니다.

개요

Android 앱에서 패스키를 지원하는 방법에는 인증 관리자, 인증 탭, WebView의 세 가지 주요 접근 방식이 있습니다. 공식 문서에는 각 옵션의 단계별 구현 세부정보가 나와 있습니다. 개발 및 유지보수 비용을 관리 가능한 수준으로 유지하면서 사용자 불편을 최소화하는 아키텍처를 선택하려면 각 옵션의 특성과 제약 조건을 높은 수준에서 이해해야 합니다. 이 가이드에서는 앱의 디자인과 기존 인증 인프라를 기반으로 적절한 접근 방식을 선택하는 방법을 설명합니다. 다음 표에서는 이러한 접근 방식을 비교합니다.

기능 인증 관리자 인증 탭 WebView
권장 사용 사례 네이티브 로그인 UI가 있는 앱 기존 웹 로그인 페이지 또는 OAuth 또는 OpenID Connect(OIDC) ID 공급업체(IdP) 재사용 기존 하이브리드 WebView 앱(퍼스트 파티 도메인만 해당)
UI 및 사용자 환경 네이티브 OS 하단 시트 및 키보드 자동 완성 통합 인증을 위한 전용 최소 브라우저 탭 네이티브 OS 하단 시트가 있는 삽입된 웹페이지
자동 완성 및 조건부 UI 지원됨(인증 관리자 자동 완성) 지원됨(WebAuthn 조건부 UI) 지원되지 않음
세션 및 사용자 인증 정보 공유 assetlinks.json 및 공유 rpId를 사용하여 웹과 앱 간에 패스키를 공유합니다(Chrome 쿠키는 공유되지 않음). Chrome과 쿠키 및 사용자 인증 정보 상태를 공유합니다(임시 브라우징을 사용하여 사용 중지할 수 있음). assetlinks.json를 사용하여 패스키를 공유하지만 Chrome에서 쿠키와 세션을 격리합니다.
디지털 애셋 링크(assetlinks.json) 신뢰 당사자 웹 도메인에서 필수 HTTPS 리디렉션의 리디렉션 URI 도메인에 필요합니다(필요하지 않은 커스텀 스키마보다 권장됨). 신뢰 당사자 웹 도메인에 필요함(외부 또는 서드 파티 IdP와 함께 사용할 수 없음)

인증 관리자

Android 앱에 네이티브 로그인 또는 등록 화면이 있는 경우 인증 관리자 Jetpack 라이브러리가 기본 권장 접근 방식입니다.

인증 관리자의 주요 장점은 패스키, 비밀번호, Google 계정으로 로그인을 하나의 간소화된 시스템 하단 시트로 통합한다는 것입니다. 사용자가 로그인할 때 앱을 종료하지 않고도 탭 한 번으로 생체 인식 인증을 완료하므로 로그인 과정이 간소화됩니다. 사용자가 초기 하단 시트를 닫고 사용자 이름 또는 비밀번호 입력란을 탭하더라도 PendingGetCredentialRequest를 사용하여 키보드 또는 드롭다운 자동 완성 추천에 패스키, 비밀번호, Google 계정으로 로그인을 직접 표시할 수 있습니다. 이 대체는 WebAuthn 조건부 UI와 동등한 네이티브 자동 완성 통합을 제공합니다.

패스키, Google 계정으로 로그인, 비밀번호 옵션이 표시된 인증 관리자 하단 시트
그림 1. 인증 관리자는 패스키, Google 계정으로 로그인, 비밀번호를 시스템 하단 시트에 통합합니다.

인증 관리자는 최신 웹 패스키 수명 주기 기능과 완전한 기능 패리티도 제공합니다. 인증 관리자를 사용하면 다음을 수행할 수 있습니다.

패스키는 Android 9(API 수준 28) 이상을 실행하는 기기에서 지원되며, 비밀번호와 같은 다른 사용자 인증 정보는 Google Play 서비스를 통해 하위 Android 버전에서 계속 지원됩니다. Android 14(API 수준 34) 이상에서는 인증 관리자가 사용자가 선택한 서드 파티 사용자 인증 정보 제공업체와도 호환됩니다. View 기반 자동 완성 통합(PendingGetCredentialRequest) 및 Signal API와 같은 추가 기능에는 Android 15(API 수준 35) 이상이 필요합니다.

웹과 앱 간에 사용자 인증 정보 공유

시작하려면 기본 요건에 따라 웹 도메인에서 디지털 애셋 링크(assetlinks.json) 파일을 호스팅하여 웹사이트와 Android 앱을 연결합니다. assetlinks.json를 통해 웹사이트와 앱을 연결하면 동일한 신뢰 당사자 ID(rpId)를 공유하므로 Chrome의 웹사이트에서 생성된 패스키가 인증 관리자를 통해 네이티브 Android 앱에서 작동하고 앱에서 생성된 패스키가 웹사이트에서 작동합니다. 인증 관리자는 웹사이트와 앱 간에 사용자 인증 정보를 공유합니다. 웹 로그인 UI 또는 IdP 페이지를 재사용하려는 경우에만 인증 탭이 필요합니다.

패스키 만들기에 설명된 대로 Android 앱 출처(android:apk-key-hash:ENCODED_SHA256_HASH, APK 서명 인증서의 패딩되지 않은 Base64URL로 인코딩된 SHA-256 해시를 사용하여 형식이 지정됨)를 확인하도록 서버를 구성해야 합니다. 앱에 네이티브 UI가 있고 패스키로 로그인하는 OS 통합 환경을 원하는 경우 인증 관리자를 선택합니다.

인증 탭

많은 서비스에서 OAuth 또는 OpenID Connect(OIDC)를 기반으로 빌드된 ID 공급업체(IdP) 마이크로서비스를 운영하거나, 기존 패스키 지원 웹 로그인 페이지를 모바일 앱에서 재사용하려고 합니다. 지금까지 앱은 이러한 흐름에 커스텀 탭을 사용했습니다. Chrome 137 및 AndroidX Browser 1.9.0부터 인증 탭은 인증 흐름에 맞게 특별히 맞춤설정된 전용 브라우저 탭을 제공합니다.

범용 브라우저 메뉴 항목 없이 최소한의 브라우저 로그인 인터페이스를 표시하는 인증 탭
그림 2. 인증 탭은 인증 흐름에 맞게 조정된 집중형 브라우저 인터페이스를 제공합니다.

표준 맞춤 탭은 범용 인앱 브라우저로 설계되어 공유 메뉴, 북마크, Chrome에서 열기와 같이 로그인과 관련이 없는 UI 요소를 표시하므로 사용자의 주의를 분산시킬 수 있습니다. 또한 인증 후 리디렉션을 수신하려면 매니페스트 파일에 인텐트 필터를 선언하고 상용구 코드를 추가해야 하며 악성 앱의 인텐트 가로채기를 방지하는 안전장치가 필요합니다.

인증 탭은 이러한 인증 관련 문제를 해결합니다. 최소화 버튼, 공유 메뉴와 같은 불필요한 브라우저 UI를 삭제하고 패스키, 비밀번호 자동 완성 등 필수 로그인 기능만 포함된 집중된 인터페이스를 제공합니다. 인증 탭은 OS 인텐트를 통해 라우팅하는 대신 커스텀 스키마 또는 디지털 애셋 링크로 인증된 HTTPS URL을 사용하여 인증 리디렉션을 인앱 콜백에 직접 전달하므로 보안이 강화되고 구현 상용구가 줄어듭니다.

세션 공유 및 맞춤 탭 대체

기본적으로 인증 탭은 쿠키 및 사용자 인증 정보 상태를 시스템 Chrome 브라우저와 직접 공유합니다. 이 공유를 통해 앱은 Chrome의 활성 로그인 세션을 활용하고 기존 WebAuthn 구현을 그대로 실행할 수 있습니다. 여기에는 조건부 UI 및 즉시 UI 모드(인증 관리자의 preferImmediatelyAvailableCredentials에 상응하는 웹)가 포함됩니다. 반대로, 사용 사례에 브라우저와 쿠키 또는 방문 기록을 공유하지 않는 격리된 인증 세션이 필요한 경우 AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true)를 호출하여 임시 탐색을 사용 설정할 수 있습니다.

androidx.browser:browser(버전 1.9.0 이상)를 앱과 함께 번들로 묶는 동안 인증 탭이 런타임에 실행되는지 여부는 사용자의 기본 브라우저에 따라 다릅니다. 기본 브라우저가 137보다 낮은 버전의 Chrome이거나 인증 탭을 지원하지 않는 서드 파티 브라우저인 경우 인증 탭은 자동으로 표준 맞춤 탭을 실행하도록 대체됩니다. 이 대체가 발생하면 인증 후 리디렉션은 인증 탭의 콜백(ActivityResultCallback)이 아닌 표준 맞춤 탭과 같이 AndroidManifest.xml의 인텐트 필터를 통해 반환됩니다. 프로덕션에서는 CustomTabsClient.isAuthTabSupported(context, provider)를 사용하여 기본 브라우저 지원을 미리 확인하여 흐름을 분기하거나 매니페스트 인텐트 필터를 유지하여 앱이 두 경로의 결과를 처리할 수 있도록 하는 것이 좋습니다. 구체적인 대체 구현 예는 Android 브라우저 도우미를 참고하세요.

OAuth 및 OIDC 보안 요구사항

인증 탭은 브라우저에서 앱으로 다시 리디렉션하는 클라이언트 측 리디렉션 채널만 보호하고 간소화합니다. OAuth 또는 OIDC 프로토콜 자체를 자동으로 보호하지는 않습니다. 특히 맞춤 탭 대체 동작을 고려할 때 네이티브 앱용 OAuth 2.0(RFC 8252)을 따라야 합니다. 구체적으로, code_challenge 및 code_verifier 매개변수를 사용하여 PKCE(Proof Key for Code Exchange, RFC 7636)를 결합하여 승인 코드 가로채기를 방지하고, state 매개변수 유효성 검사를 통해 교차 사이트 요청 위조(CSRF) 및 세션 고정 공격을 방지하고, OpenID Connect에서 nonce 매개변수 생성 및 유효성 검사를 통해 ID 토큰 재생 공격을 방지합니다. 이러한 보호 조치가 마련되어 있으므로 Google은 웹 기반 로그인 아키텍처를 표준 맞춤 탭에서 인증 탭으로 이전할 것을 권장합니다.

WebView

일부 앱은 하이브리드 WebView 아키텍처를 기반으로 빌드되어 로그인 화면만 네이티브 UI(인증 관리자) 또는 브라우저 탭(인증 탭)으로 분리하는 것이 실용적이지 않습니다. 이 경우 WebView 내에서 직접 WebAuthn 지원을 사용 설정할 수 있습니다.

WebView에서 패스키를 사용하려면 AndroidX WebKit 라이브러리(androidx.webkit:webkit 버전 1.12.0 이상)와 인증 관리자 종속 항목(androidx.credentials:credentials 및 androidx.credentials:credentials-play-services-auth)을 모두 build.gradle 파일에 추가합니다. 그런 다음 WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)를 사용하여 기능 지원을 확인하고 WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP)를 호출하여 WebAuthn 지원을 명시적으로 사용 설정합니다. 이 구성은 WebView의 웹페이지에서 인증 관리자로 패스키 생성 및 인증 요청을 자동으로 연결합니다.

도메인 및 UX 제약조건

네이티브 인증 관리자 통합과 마찬가지로 기본 요건에 따라 신뢰 당사자 웹 도메인에 디지털 애셋 링크(assetlinks.json) 파일을 호스팅하여 앱을 연결해야 합니다. 서버는 android:apk-key-hash:ENCODED_SHA256_HASH(Base64URL로 인코딩된 SHA-256 인증서 해시)를 출처로 수신합니다. 이 접근 방식은 Android 앱의 서명 인증서를 신뢰하기 위해 신뢰 당사자 도메인에서 assetlinks.json를 호스팅해야 하므로 신뢰 당사자 웹 도메인을 제어하는 경우에만 작동합니다(퍼스트 파티 웹 로그인). 인증 흐름이 앱 패키지의 assetlinks.json를 호스팅할 수 없는 외부 또는 서드 파티 IdP로 리디렉션되는 경우 WebView 대신 인증 탭(또는 인증 관리자를 통한 네이티브 Google 계정으로 로그인)을 사용해야 합니다.

두 가지 UX 및 기능적 제약 조건에 유의하세요. WebView는 조건부 UI(사용자가 입력란에 포커스를 맞출 때 mediation: "conditional" 자동 완성 통합)를 지원하지 않으며 시스템 Chrome 브라우저와 쿠키 또는 로그인 세션을 공유하지 않습니다. 이러한 제약 조건으로 인해 Google에서는 새로운 인증 흐름을 설계할 때 인증 관리자 또는 인증 탭을 사용할 것을 권장합니다. 하지만 주요 아키텍처 변경 없이 기존 퍼스트 파티 하이브리드 앱에 패스키 지원을 추가하려면 패스키를 WebView와 통합하면 됩니다.

요약

앱의 현재 UI 및 인증 인프라에서 시작하면 올바른 패스키 접근 방식을 선택하는 데 도움이 됩니다.

  • 앱에 네이티브 로그인 UI가 있고 브라우저 화면으로 전환하지 않고 OS 통합 환경을 원하는 경우 인증 관리자를 선택하여 패스키로 로그인합니다.
  • OAuth 또는 OIDC IdP 마이크로서비스를 운영하거나, 외부 IdP로 리디렉션하거나, 기존 패스키 지원 웹 로그인 페이지(조건부 UI 포함)를 재사용하고 활성 브라우저 세션을 Chrome과 공유하려면 인증 탭을 채택하고 네이티브 앱용 OAuth 2.0(RFC 8252)의 보안 요구사항(특히 PKCE, state, nonce)을 구현하세요.
  • 앱이 로그인 시 내장된 퍼스트 파티 웹 화면을 유지해야 하는 하이브리드 WebView 아키텍처를 기반으로 빌드된 경우, 조건부 UI 지원 및 격리된 쿠키가 없다는 점을 고려하면서 WebView를 사용하세요.

다음 단계