Passkey cho Ứng dụng gốc (Native App): Triển khai Gốc vs. WebView

Lưu ý: System và Embedded WebView thường được kết hợp, trong đó System WebView xử lý đăng nhập (với tính năng chia sẻ thông tin xác thực tự động), sau đó Embedded WebView hiển thị quản lý passkey trong phần cài đặt.

Các yếu tố quyết định chính:

• Đăng nhập dựa trên OAuth? → System WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• Muốn tái sử dụng xác thực web trong vỏ gốc (native shell)? → Embedded WebView (WKWebView, Android WebView với WebKit 1.12.1+)
• Xây dựng ứng dụng ưu tiên trải nghiệm gốc? → Triển khai gốc (Apple AuthenticationServices, Google Credential Manager)

Các nền tảng di động hiện đại cung cấp ba cách tiếp cận riêng biệt để tích hợp passkey vào ứng dụng gốc của bạn, mỗi cách có sự đánh đổi khác nhau về trải nghiệm người dùng, độ phức tạp kỹ thuật và khả năng tương thích OAuth:

1. Triển khai gốc: Xây dựng luồng passkey trực tiếp vào ứng dụng của bạn bằng cách sử dụng các API của nền tảng (iOS AuthenticationServices, Android Credential Manager). Cung cấp trải nghiệm người dùng tốt nhất với xác thực sinh trắc học mượt mà, nhưng yêu cầu nỗ lực triển khai kỹ thuật từ trung bình đến cao.

2. System WebView: Sử dụng thành phần trình duyệt của nền tảng (iOS ASWebAuthenticationSession / SFSafariViewController, Android Chrome Custom Tabs) để xử lý xác thực. Tuyệt vời cho các luồng đăng nhập dựa trên OAuth và chia sẻ thông tin xác thực với trình duyệt hệ thống.

3. Embedded WebView: Nhúng chế độ xem web (web view) có thể tùy chỉnh (iOS WKWebView, Android WebView) vào trong ứng dụng của bạn để tái sử dụng xác thực web với khung ứng dụng gốc. Cung cấp giao diện giống như bản gốc mà không có thanh URL và kiểm soát hoàn toàn giao diện người dùng của chế độ xem web. Yêu cầu thiết lập bổ sung bao gồm quyền và entitlements (iOS), và cấu hình WebView với AndroidX WebKit 1.12.1+ (Android) để bật chức năng passkey.

Sự lựa chọn đúng đắn phụ thuộc vào kiến trúc xác thực của ứng dụng, liệu bạn có sử dụng các nhà cung cấp OAuth hay không, bạn cần kiểm soát bao nhiêu đối với giao diện người dùng và liệu bạn đang xây dựng ứng dụng ưu tiên bản gốc hay tái sử dụng các thành phần web.

Whitepaper Passkey cho enterprise. Hướng dẫn thực tế, mẫu triển khai và KPI cho chương trình passkeys.

Nhận whitepaper

Triển khai passkey gốc cung cấp trải nghiệm người dùng tối ưu, với các luồng xác thực được xây dựng trực tiếp vào giao diện người dùng của ứng dụng bằng cách sử dụng các API dành riêng cho nền tảng. Người dùng được hưởng lợi từ các hộp thoại gốc của nền tảng, xác minh sinh trắc học mượt mà và thời gian đăng nhập nhanh nhất có thể.

Khi nào nên chọn Triển khai gốc:

• Xây dựng ứng dụng gốc mới hoặc tái cấu trúc xác thực thành các màn hình gốc
• Muốn trải nghiệm người dùng tốt nhất có thể với xác thực tức thì, không tiếng ồn
• Lời nhắc passkey tự động khi khởi động ứng dụng: Các triển khai gốc có thể sử dụng preferImmediatelyAvailableCredentials để hiển thị lớp phủ passkey tự động khi có sẵn passkey, mang lại trải nghiệm đăng nhập nhanh nhất mà không yêu cầu nhập định danh
• Cần kiểm soát hoàn toàn giao diện và luồng xác thực
• Sẵn sàng đầu tư vào triển khai dành riêng cho nền tảng (iOS Swift, Android Kotlin)

Ưu điểm chính: preferImmediatelyAvailableCredentials()

Các triển khai gốc có thể tận dụng preferImmediatelyAvailableCredentials() để tạo lớp phủ passkey tự động xuất hiện ngay lập tức khi khởi động ứng dụng khi có sẵn passkey. Luồng không cần tên người dùng này mang lại trải nghiệm đăng nhập nhanh nhất có thể-người dùng nhìn thấy passkey của họ ngay lập tức mà không cần nhập định danh trước. Khả năng này là độc quyền đối với các triển khai gốc và không có sẵn trong các biến thể WebView.

Biểu đồ dưới đây minh họa cách xác thực gốc mang lại hành trình người dùng nhanh hơn so với cách tiếp cận Conditional UI của WebView:

Lớp phủ tự động của bản gốc cung cấp UX vượt trội với tỷ lệ sử dụng passkey cao hơn vì xác thực bắt đầu ngay lập tức khi khởi chạy ứng dụng, trong khi các triển khai WebView yêu cầu người dùng tương tác với các trường nhập liệu trước.

Tổng quan về Yêu cầu kỹ thuật:

Tích hợp passkey gốc yêu cầu sự tin cậy mật mã giữa ứng dụng và miền web của bạn. Nếu không có điều đó, hệ điều hành sẽ từ chối tất cả các hoạt động WebAuthn. Yêu cầu chính:

1. Các tệp liên kết ứng dụng-miền (App-Domain Association Files) được lưu trữ tại /.well-known/
2. Relying Party ID chính xác khớp với miền web của bạn
3. Các khả năng dành riêng cho nền tảng (được trình bày chi tiết trong Phần 4)

Lợi ích chính: passkey được tạo trên trang web của bạn hoạt động liền mạch trong ứng dụng của bạn và ngược lại.

Triển khai passkey một cách gốc rễ trên iOS liên quan đến framework AuthenticationServices của Apple, cung cấp API cho các hoạt động WebAuthn:

Các thành phần chính:

• ASAuthorizationController: Quản lý luồng xác thực
• ASAuthorizationPlatformPublicKeyCredentialProvider: Tạo các yêu cầu passkey
• Ba chế độ UI riêng biệt để xử lý đăng nhập passkey:
  • Đăng nhập bằng trường văn bản (Textfield login): Trường tên người dùng truyền thống với đăng nhập passkey bắt đầu khi nút gửi (submit) được nhấn
  • Lớp phủ mô đun Passkey (Passkey modal overlay): Hộp thoại OS liệt kê các passkey có sẵn
  • Conditional UI: Gợi ý passkey trên thanh QuickType phía trên bàn phím

Mẹo phát triển

• Lưu trữ AASA vào bộ nhớ đệm (Caching): Apple lưu trữ tệp AASA rất mạnh (lên đến 24 giờ), điều này có thể gây khó chịu khi thử nghiệm. Giải pháp: Bật Chế độ Nhà phát triển (Developer Mode) trên thiết bị thử nghiệm của bạn và thêm ?mode=developer vào URL AASA của bạn để buộc tải tệp mới nhất
• Kiểm tra hiệu suất: Kiểm tra với các tài khoản iCloud chứa hàng trăm thông tin xác thực để quan sát độ trễ trong thế giới thực. Lớp phủ hệ thống có thể hiển thị một chút chậm trễ với nhiều passkey được lưu trữ

Triển khai passkey gốc của Android sử dụng API Credential Manager (hoặc API FIDO2 cũ hơn để tương thích ngược):

Các thành phần chính:

• CredentialManager: API trung tâm cho tất cả các hoạt động thông tin xác thực
• CreatePublicKeyCredentialRequest: Dành cho đăng ký passkey
• GetCredentialRequest: Dành cho xác thực passkey
• Hai chế độ UI chính:
  • Đăng nhập bằng trường văn bản: Trường tên người dùng truyền thống với đăng nhập passkey bắt đầu khi nút gửi được nhấn
  • Lớp phủ mô đun Passkey: Hộp thoại OS liệt kê các passkey có sẵn

Lưu ý: Android hiện thiếu các gợi ý bàn phím Conditional UI của iOS trong các ứng dụng gốc (mặc dù Conditional UI hoạt động trong các ứng dụng web)

Triển khai passkey một cách gốc rễ có những thách thức quan trọng và bài học rút ra: Việc tích hợp ở cấp hệ điều hành có thể làm lộ ra các vấn đề trên các thiết bị và phiên bản hệ điều hành khác nhau.

1. Ví dụ, nhóm của chúng tôi gặp phải các vấn đề như tính năng lưu trữ mạnh của Apple đối với tệp apple-app-site-association (được sử dụng cho liên kết thông tin xác thực ứng dụng/web) và những khác biệt nhỏ về UI trong một số lời nhắc sinh trắc học OEM của Android.
2. Hơn nữa, hãy xem xét rằng trong một số tình huống doanh nghiệp, các thiết bị được quản lý có thể bị vô hiệu hóa tính năng đồng bộ hóa passkey theo chính sách. Trong môi trường doanh nghiệp nơi tính năng đồng bộ hóa iCloud Keychain hoặc Google Password Manager bị tắt, passkey trở nên gắn liền với thiết bị (device-bound) và sẽ không chuyển vùng (roam) - một tình huống quan trọng cần lập kế hoạch (ví dụ: đảm bảo người dùng vẫn có thể đăng nhập nếu họ nhận được điện thoại mới).
3. Ngoài ra, các ứng dụng trình quản lý mật khẩu của bên thứ ba có thể ảnh hưởng đến luồng. Ví dụ, nếu người dùng có một trình quản lý mật khẩu như 1Password được thiết lập như một nhà cung cấp thông tin xác thực đang hoạt động, nó thường sẽ can thiệp vào việc tạo và lưu trữ passkey, ưu tiên hơn trình quản lý thông tin xác thực gốc của nền tảng.

Mặc dù bạn có thể triển khai passkey bằng cách sử dụng các API nền tảng gốc, các SDK được xây dựng có mục đích sẽ tăng tốc đáng kể sự phát triển bằng cách xử lý tính phức tạp của WebAuthn, các trường hợp ngoại lệ và cung cấp hệ thống từ xa (telemetry) tích hợp. SDK cũng cung cấp các giao diện có thể giả lập để thử nghiệm đơn vị (unit testing) (rất quan trọng vì bạn không thể kiểm tra sinh trắc học trong các trình mô phỏng).

Khuyến nghị: Đối với các triển khai gốc, chúng tôi khuyên bạn nên sử dụng SDK Corbado (SDK Passkey Swift cho iOS, SDK Passkey Kotlin cho Android) để xử lý nhiều trường hợp ngoại lệ được phát hiện thông qua các triển khai sản xuất, cung cấp thêm hệ thống từ xa và thử nghiệm.

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

System WebViews sử dụng thành phần trình duyệt gốc của nền tảng để xử lý xác thực trong ứng dụng của bạn. Không giống như các triển khai hoàn toàn gốc, System WebViews hiển thị nội dung web bằng cách sử dụng trình duyệt hệ thống thực tế (Safari trên iOS, Chrome trên Android), duy trì cookie dùng chung, thông tin xác thực đã lưu và các chỉ báo bảo mật trình duyệt quen thuộc.

Khi nào nên chọn System WebView:

• Ứng dụng của bạn sử dụng đăng nhập dựa trên OAuth: System WebView là cách tiếp cận được khuyến nghị cho các luồng OAuth2/OIDC, cung cấp xác thực an toàn
• Xác thực dựa trên web hiện có mà bạn muốn tái sử dụng trong các ứng dụng di động
• Cần hỗ trợ nhiều phương thức xác thực (mật khẩu, đăng nhập mạng xã hội, passkey) mà không cần xây dựng lại từ đầu
• Muốn duy trì một cơ sở mã xác thực duy nhất trên web và thiết bị di động

Ưu điểm chính:

• Khả năng tương thích OAuth: Được xây dựng có mục đích cho các luồng xác thực OAuth/OIDC
• Chỉ báo bảo mật: Người dùng nhìn thấy URL thực tế và chứng chỉ SSL, xây dựng niềm tin
• Nỗ lực triển khai thấp: Cần mã gốc tối thiểu
• UX nhất quán: Giao diện trình duyệt quen thuộc mà người dùng đã tin tưởng

Các thành phần nền tảng:

• iOS: ASWebAuthenticationSession (được khuyến nghị cho các luồng xác thực) hoặc SFSafariViewController (duyệt web chung)
• Android: Chrome Custom Tabs (CCT)

Các công ty lớn như Google và GitHub đã áp dụng cách tiếp cận này để thêm đăng nhập bằng passkey vào các ứng dụng di động của họ thông qua các lớp phủ WebView trên các trang xác thực web hiện có. Điều này hoạt động tốt khi việc xây dựng lại xác thực hoàn toàn gốc không khả thi ngay lập tức.

iOS cung cấp hai thành phần System WebView chính cho xác thực:

ASWebAuthenticationSession (Được khuyến nghị cho Xác thực):

• Được xây dựng có mục đích cho OAuth/OIDC và các luồng đăng nhập an toàn
• Tự động nhắc người dùng rằng ứng dụng muốn xác thực
• Chia sẻ cookie và thông tin xác thực với Safari
• Hỗ trợ passkey thông qua iCloud Keychain

SFSafariViewController (Duyệt web chung):

• Trải nghiệm Safari đầy đủ trong ứng dụng
• Hiển thị thanh URL và các chỉ báo bảo mật
• Không chia sẻ cookie Safari trên iOS 11+; sử dụng ASWebAuthenticationSession khi yêu cầu chia sẻ phiên Safari
• Ít có thể tùy chỉnh hơn nhưng đáng tin cậy hơn đối với người dùng

Nếu ứng dụng của bạn sử dụng đăng nhập dựa trên OAuth, ASWebAuthenticationSession là lựa chọn được khuyến nghị vì nó được thiết kế riêng cho các tình huống xác thực và cung cấp sự cân bằng tốt nhất giữa bảo mật và trải nghiệm người dùng.

Chrome Custom Tabs (CCT) cung cấp trải nghiệm xác thực được hỗ trợ bởi Chrome trong ứng dụng của bạn:

Các tính năng chính:

• Chia sẻ cookie và thông tin xác thực với trình duyệt Chrome
• Hiển thị URL và các chỉ báo bảo mật
• Có thể tùy chỉnh màu sắc thanh công cụ và thương hiệu
• Làm nóng (Pre-warming) để có thời gian tải nhanh hơn

Tích hợp OAuth: Chrome Custom Tabs tương đương với iOS ASWebAuthenticationSession của Android, cung cấp hỗ trợ OAuth rất tốt đồng thời duy trì quyền truy cập vào các passkey đã lưu.

Thử passkeys trong demo trực tiếp.

Thử passkeys

Embedded WebViews cung cấp khả năng kiểm soát hoàn toàn việc hiển thị nội dung web trong ứng dụng của bạn, cho phép thao tác trực tiếp với cookie, phiên và điều hướng mà không có thanh URL. Tuy nhiên, sự kiểm soát này đi kèm với các yêu cầu kỹ thuật bổ sung để kích hoạt chức năng passkey.

Khi nào nên chọn Embedded WebView:

• Trải nghiệm giống như bản gốc: Ứng dụng của bạn đã nhúng xác thực trong một chế độ xem web có thể tùy chỉnh để duy trì giao diện và cảm giác của bản gốc, và bạn muốn giữ trải nghiệm người dùng nhất quán này
• Cần kiểm soát phiên/cookie: Ứng dụng của bạn yêu cầu thao tác trực tiếp với các mã thông báo (token) xác thực và trạng thái phiên sau khi xác thực OAuth hoàn tất
• Luồng xác thực hiện có trong đó xác thực System WebView trả về mã ủy quyền nhưng không có phiên trong các bối cảnh nhúng
• Phải duy trì trạng thái xác thực trên nhiều màn hình web nhúng
• Chỉ xác thực của bên thứ nhất (First-party authentication): Ứng dụng của bạn xử lý xác thực trực tiếp
• AndroidX WebKit 1.12.1+ với tính năng phát hiện lúc chạy
• Chấp nhận giới hạn Conditional UI đối với Đăng nhập (không được hỗ trợ trong Embedded WebView), không liên quan đến cài đặt quản lý

Bối cảnh quan trọng:

Nhiều ứng dụng sử dụng cách tiếp cận lai: System WebView xử lý xác thực OAuth ban đầu (nơi passkey hoạt động liền mạch), sau đó chuyển sang Embedded WebView cho sau xác thực để quản lý passkey trong phần cài đặt. Thách thức nảy sinh khi cố gắng sử dụng passkey trực tiếp trong Embedded WebViews.

Yêu cầu kỹ thuật:

Embedded WebViews yêu cầu thiết lập bổ sung so với System WebViews:

1. iOS: Cấu hình entitlements Associated Domains, tệp AASA
2. Android: AndroidX WebKit 1.12.1+ với cấu hình WebAuthn của WebView (yêu cầu phát hiện tính năng)
3. Cả hai: Các tệp liên kết well-known được cấu hình đúng và Digital Asset Links

Các thành phần nền tảng:

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

Sự đánh đổi:

• Độ phức tạp trung bình: Yêu cầu cấu hình WebView (Android WebKit 1.12.1+) và thiết lập entitlements (iOS)
• Mức độ áp dụng passkey thấp hơn: Người dùng có thể gặp nhiều ma sát hơn so với bản gốc
• Conditional UI không được hỗ trợ: Tự động điền passkey trong các trường nhập liệu không hoạt động trong Android Embedded WebView
• Hỗ trợ nền tảng hạn chế: Một số tính năng có thể không hoạt động nhất quán (ví dụ: tự động tạo passkey)

Khi triển khai passkey thông qua WebViews, việc hiểu rõ sự khác biệt giữa System WebViews và Embedded WebViews là rất quan trọng. Ba cách tiếp cận được phác thảo ở trên (Triển khai gốc, System WebView và Embedded WebView) mỗi cách phục vụ các trường hợp sử dụng khác nhau.

Trên iOS, bạn có nhiều tùy chọn để hiển thị nội dung web trong ứng dụng:

• WKWebView là thành phần WebView có thể tùy chỉnh thuộc khung WebKit (được giới thiệu trong iOS 8). Nó cung cấp cho bạn nhiều quyền kiểm soát đối với giao diện và hành vi của nội dung web.
• SFSafariViewController là một view controller được cung cấp bởi Apple đóng vai trò như một trình duyệt Safari nhẹ trong ứng dụng của bạn. Nó sử dụng công cụ của Safari. Trên iOS 11+, nó có kho lưu trữ cookie riêng và không chia sẻ cookie của Safari. Sử dụng ASWebAuthenticationSession khi yêu cầu chia sẻ phiên Safari.
• SFAuthenticationSession / ASWebAuthenticationSession là các phiên xác thực web chuyên biệt (có sẵn từ iOS 11/12) dành riêng cho các luồng đăng nhập OAuth/OpenID hoặc đăng nhập an toàn khác. Các phiên này cũng tận dụng Safari ở bên dưới, nhưng tập trung vào các luồng xác thực và tự động xử lý các vấn đề như cookie dùng chung và Đăng nhập một lần (SSO).

Trên Android, các lựa chọn chính là:

• Android WebView là tiện ích WebView tiêu chuẩn (android.webkit.WebView), về cơ bản là một trình duyệt mini có thể được nhúng vào các hoạt động (activities) của bạn. Nó có khả năng tùy chỉnh cao nhưng chạy trong tiến trình (process) của ứng dụng của bạn.
• Chrome Custom Tabs (CCT) là một tính năng mở một tab được hỗ trợ bởi Chrome trong bối cảnh ứng dụng của bạn. Custom Tabs xuất hiện như một phần của ứng dụng của bạn nhưng được hỗ trợ bởi trình duyệt Chrome (nếu được cài đặt) với các tính năng như tải trước, cookie dùng chung và thanh URL quen thuộc để người dùng tin tưởng.

Trong các phần tiếp theo, chúng ta sẽ đi sâu hơn một chút vào các loại WebView này đối với iOS và Android, đồng thời thảo luận xem loại nào có thể phù hợp nhất cho các luồng xác thực passkey.

Đăng ký Passkeys Substack để nhận tin mới nhất.

Đăng ký

Nền tảng của Apple cung cấp ba tùy chọn WebView được liệt kê ở trên. Sự lựa chọn của bạn sẽ ảnh hưởng đến mức độ trơn tru của việc sử dụng passkey bên trong ứng dụng:

Để kiểm tra các hành vi WebView khác nhau trong iOS, chúng tôi khuyên bạn nên dùng ứng dụng WebView - WKWebView and UIWebView rendering.

WKWebView là một thành phần WebView linh hoạt cho iOS. Các nhà phát triển có thể nhúng WKWebView để hiển thị nội dung web với mức độ kiểm soát cao đối với giao diện người dùng và hành vi. WKWebView sử dụng cùng một công cụ kết xuất như Safari, vì vậy nó rất hiệu quả và hỗ trợ các tính năng web hiện đại. Về lý thuyết, WKWebView có thể xử lý WebAuthn (và do đó là passkey) nếu được cấu hình đúng cách, nhưng lưu ý rằng một số tính năng trình duyệt nâng cao có thể bị hạn chế vì lý do bảo mật. Một điều cần chú ý là WKWebView mặc định không chia sẻ cookie hoặc dữ liệu keychain với Mobile Safari. Người dùng có thể phải đăng nhập lại vì phiên WebView của họ bị cô lập với phiên của Safari. Ngoài ra, bởi vì nội dung WKWebView có thể được tùy chỉnh hoàn toàn bởi ứng dụng, người dùng không nhìn thấy thanh địa chỉ hoặc giao diện người dùng Safari – điều này rất tốt cho việc xây dựng thương hiệu, nhưng có nghĩa là người dùng có ít gợi ý hơn để xác minh tính hợp pháp của trang (một mối quan tâm đối với chống lừa đảo). Một số ứng dụng thậm chí đã lạm dụng WKWebView để tiêm mã (inject scripts) hoặc thay đổi nội dung (ví dụ: TikTok được ghi nhận là đã tiêm JS theo dõi qua trình duyệt trong ứng dụng của họ), do đó người ta phải cẩn thận sử dụng WKWebView một cách an toàn, đáng tin cậy cho người dùng.

SFSafariViewController cung cấp trải nghiệm Safari trong ứng dụng. Khi bạn mở URL bằng SFSafariViewController, gần giống như mở nó trong trình duyệt Safari thực, ngoại trừ người dùng vẫn ở trong giao diện người dùng của ứng dụng của bạn. Lợi thế đối với passkey là đáng kể: bởi vì nó về cơ bản là Safari, iCloud Keychain và passkey đã lưu của người dùng có thể truy cập được. Lưu ý rằng cookie không được chia sẻ trên iOS 11+. Điều này có nghĩa là nếu người dùng đã có passkey cho trang web của bạn, Safari có thể tìm thấy nó và thậm chí hiển thị tính năng tự động điền Conditional UI để đăng nhập dễ dàng. SFSafariViewController ít có thể tùy chỉnh hơn (bạn không thể thay đổi thanh công cụ của nó nhiều), nhưng nó tự động xử lý rất nhiều tính năng bảo mật và quyền riêng tư. Thanh URL được hiển thị, hoàn chỉnh với biểu tượng ổ khóa cho HTTPS, mang lại sự tự tin cho người dùng rằng họ đang truy cập đúng miền. Nói chung, SFSafariViewController được coi là an toàn hơn WKWebView thô và đơn giản hơn để triển khai (Apple cung cấp nó như một thành phần có thể thêm ngay). Sự đánh đổi chính là bạn hy sinh một số quyền kiểm soát đối với giao diện. Đối với luồng xác thực, điều đó thường được chấp nhận. Ưu tiên ở đây là tính bảo mật và dễ đăng nhập, điều mà SFSafariViewController xuất sắc thực hiện bằng cách sử dụng ngữ cảnh của Safari.

SFAuthenticationSession / ASWebAuthenticationSession – Các lớp này (lớp sau là tên thân thiện với Swift mới hơn) được xây dựng dành riêng cho các luồng đăng nhập như OAuth hoặc OpenID Connect. Khi bạn cần xác thực người dùng thông qua một trang web (có lẽ là với một nhà cung cấp định danh - IdP - bên ngoài), các phiên này là lựa chọn được khuyến nghị trên iOS. Chúng rất giống với SFSafariViewController ở chỗ chúng sử dụng trình duyệt Safari ở bên dưới và chia sẻ cookie/lưu trữ với Safari. Sự khác biệt chính là SFAuthenticationSession sẽ luôn nhắc người dùng rằng ứng dụng muốn xác thực bằng một trang web (để người dùng nhận biết) và nó sẽ tự động sử dụng phiên Safari hiện tại của người dùng nếu có sẵn.

Lợi ích là trải nghiệm SSO liền mạch – nếu người dùng đã đăng nhập vào nhà cung cấp trong Safari, phiên này có thể sử dụng cookie đó để tránh phải đăng nhập lại. Đối với passkey, điều này rất quan trọng vì nó có nghĩa là bất kỳ passkey nào được lưu trữ trong Safari/iCloud Keychain cũng có thể được sử dụng ở đây. Hướng dẫn chính thức của Apple là sử dụng ASWebAuthenticationSession cho bất kỳ luồng nào giống như đăng nhập. Ưu điểm là quyền riêng tư được nâng cao (ứng dụng của bạn không bao giờ nhìn thấy thông tin xác thực hoặc cookie, Safari xử lý điều đó) và hỗ trợ SSO tích hợp. Nhược điểm là nó bị giới hạn ở các luồng xác thực (bạn sẽ không sử dụng nó để chỉ hiển thị nội dung web tùy ý trong ứng dụng của mình). Tóm lại, nếu bạn chọn cách tiếp cận WebView trên iOS, ASWebAuthenticationSession thường là lựa chọn tốt nhất để triển khai passkey vì nó an toàn, chia sẻ trạng thái với Safari và được xây dựng có mục đích cho xác thực.

Xem có bao nhiêu người thực sự dùng passkeys.

Xem dữ liệu adoption

Trên Android, quyết định về WebView là giữa WebView cổ điển và Chrome Custom Tabs:

Để kiểm tra hành vi WebView khác nhau trên Android, chúng tôi khuyên bạn nên sử dụng ứng dụng WebView vs Chrome Custom Tabs.

Android WebView (android.webkit.WebView) là một thành phần cho phép bạn nhúng các trang web vào bố cục hoạt động (activity layout) của mình. Nó tương tự như WKWebView ở chỗ nó cung cấp cho bạn toàn quyền kiểm soát: bạn có thể chặn điều hướng, tiêm JavaScript, tùy chỉnh UI, v.v. Nó cũng chạy trong tiến trình của ứng dụng của bạn. Sử dụng WebView cho passkey có nghĩa là ứng dụng của bạn tải trang đăng nhập web của bạn, và trang đó có thể khởi tạo WebAuthn. Android WebView hiện đại hỗ trợ WebAuthn (với điều kiện việc triển khai WebView của thiết bị được cập nhật thông qua Android System WebView hoặc thành phần Chrome). Một cân nhắc lớn: theo mặc định, một Android WebView không chia sẻ cookie hoặc thông tin xác thực đã lưu với trình duyệt Chrome của người dùng. Vì vậy, bất kỳ passkey nào được tạo hoặc sử dụng trong WebView đều có thể không được Chrome biết đến và ngược lại. Sự cô lập này có thể tốt cho bảo mật (ứng dụng của bạn không thể đọc cookie trình duyệt), nhưng nó có thể buộc người dùng phải đăng nhập lại nếu họ đã xác thực trong Chrome. Một vấn đề khác là niềm tin. Một WebView đơn thuần không hiển thị URL hoặc biểu tượng ổ khóa SSL, vì vậy người dùng phải hoàn toàn tin tưởng ứng dụng của bạn để không lừa đảo họ. Google thậm chí đã cấm sử dụng WebView cho đăng nhập Google OAuth do các rủi ro lừa đảo tiềm ẩn. Về hiệu suất, WebView thì ổn, nhưng chúng có thể chậm hơn hoặc tiêu tốn nhiều bộ nhớ hơn so với việc sử dụng trình duyệt mặc định của người dùng, đặc biệt là khi tải các trang nặng.

Chrome Custom Tabs (CCT) là một cách tiếp cận lai. Chúng cho phép ứng dụng của bạn mở một trang được Chrome hiển thị trông giống như một phần của ứng dụng của bạn. Bạn có thể tùy chỉnh màu thanh công cụ, thêm logo ứng dụng, v.v., nhưng nội dung được hiển thị bởi Chrome trong một tiến trình riêng biệt. Đối với passkey, CCT có một số lợi ích: chúng chia sẻ cookie và thông tin xác thực của người dùng với trình duyệt Chrome, có nghĩa là nếu người dùng đã lưu một passkey thông qua Chrome (Google Password Manager), Custom Tab có thể truy cập nó. Người dùng cũng sẽ nhìn thấy URL thực tế và các chỉ báo bảo mật, điều này xây dựng niềm tin. Hiệu suất thường tốt hơn – Chrome có thể được "làm nóng" trong nền để tải nhanh hơn. Và quan trọng nhất, bảo mật rất mạnh: bởi vì nó về cơ bản là ứng dụng Chrome, các tính năng như Google Safe Browsing bảo vệ phiên, và ứng dụng của bạn không thể tiêm các mã lệnh (scripts) tùy ý vào trang (ngăn chặn một số cuộc tấn công nhất định).

Nhược điểm là nó yêu cầu người dùng phải cài đặt Chrome (hoặc trình duyệt được hỗ trợ) và cập nhật. Hầu hết người dùng Android đều có, nhưng trên một số thiết bị ở các khu vực nhất định, điều này có thể là một vấn đề. Nhìn chung, nếu bạn đi với cách tiếp cận web nhúng trên Android, Chrome Custom Tabs được khuyến nghị cho các luồng passkey, vì chúng cung cấp sự cân bằng tốt về tích hợp và bảo mật. Trên thực tế, chúng tương tự như SFSafariViewController/ASWebAuthSession của iOS ở nhiều khía cạnh – tận dụng trình duyệt mặc định cho xác thực.

(Nói thêm: WKWebView vs SFSafariViewController của Apple và WebView vs CCT của Android có nhiều điểm tương đồng. Cả Safari VC và Chrome Tabs đều chia sẻ trạng thái trình duyệt và cung cấp bảo mật tốt hơn, trong khi WKWebView/Android WebView cung cấp nhiều quyền kiểm soát hơn nhưng cô lập nội dung web. Đối với passkey, việc chia sẻ trạng thái (cookie, kho thông tin xác thực) thường được mong muốn để passkey có thể được truy cập và tạo ra một cách liền mạch.)

Bất kể bạn chọn cách tiếp cận triển khai nào, các yêu cầu kỹ thuật nhất định phải được đáp ứng để bật chức năng passkey. Phần này cung cấp hướng dẫn toàn diện về cấu hình các tệp liên kết well-known, entitlements iOS, và cấu hình WebView Android.

Lưu ý về các Thiết bị được quản lý (Managed Devices): Hành vi của Passkey thay đổi đáng kể trên các thiết bị được quản lý khi các chính sách Quản lý Thiết bị Di động (MDM) kiểm soát việc lưu trữ thông tin xác thực. Để thử nghiệm passkey trên các thiết bị được quản lý, hãy xem Passkey trên Các thiết bị iOS & Android được quản lý.

Các luồng WebView Gốc và Nhúng yêu cầu các tệp liên kết để thiết lập sự tin cậy mật mã giữa ứng dụng và miền web của bạn. System WebView (ASWebAuthenticationSession) và Chrome Custom Tabs không yêu cầu liên kết ứng dụng tới trang web.

Tệp AASA thiết lập kết nối giữa ứng dụng iOS và miền web của bạn, cho phép passkey hoạt động trên cả hai nền tảng.

Vị trí tệp: https://yourdomain.com/.well-known/apple-app-site-association

Yêu cầu cấu hình:

• Lưu trữ tại /.well-known/apple-app-site-association trên miền của bạn
• Phục vụ qua HTTPS với chứng chỉ SSL hợp lệ
• Content-Type: application/json
• Không có chuyển hướng (redirects) trên đường dẫn .well-known
• Bao gồm Team ID và Bundle ID của ứng dụng

Ví dụ về Tệp AASA:

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

Bộ nhớ đệm AASA và Thử nghiệm:

Apple lưu trữ các tệp AASA rất mạnh (lên đến 24-48 giờ) bằng CDN, điều này có thể gây khó chịu cho quá trình phát triển và thử nghiệm. Để bỏ qua bộ nhớ đệm trong quá trình phát triển:

1. Bật Chế độ nhà phát triển (Developer Mode) trên thiết bị thử nghiệm của bạn
2. Thêm ?mode=developer vào miền liên kết của bạn trong Xcode
3. Điều này buộc iOS phải lấy tệp AASA mới nhất trực tiếp từ máy chủ của bạn

⚠️ Quan trọng: KHÔNG sử dụng ?mode=developer trong các bản phát hành sản xuất. Tham số này chỉ dành cho mục đích phát triển - việc sử dụng nó trong môi trường sản xuất sẽ ngăn iOS phát hiện đúng cách tệp AASA của bạn, làm hỏng chức năng passkey.

Xác thực: Sử dụng AASA Validator của Apple để xác minh cấu hình của bạn.

Android sử dụng Digital Asset Links để xác minh mối quan hệ giữa ứng dụng và trang web của bạn.

Vị trí tệp: https://yourdomain.com/.well-known/assetlinks.json

Yêu cầu cấu hình:

• Lưu trữ tại /.well-known/assetlinks.json trên miền của bạn
• Phục vụ qua HTTPS với chứng chỉ hợp lệ
• Content-Type: application/json
• Bao gồm dấu vân tay SHA256 (từ chứng chỉ ký) của ứng dụng

Ví dụ về Tệp 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"
            ]
        }
    }
]

Xác thực: Sử dụng Trình tạo Digital Asset Links của Google để tạo và xác minh cấu hình của bạn.

Các ứng dụng iOS yêu cầu các entitlements thích hợp để truy cập chức năng passkey. Các yêu cầu có một chút khác biệt dựa trên cách tiếp cận triển khai của bạn.

Tệp entitlements (thường có tên là Runner.entitlements trong các ứng dụng Flutter hoặc YourApp.entitlements trong các dự án iOS gốc) xác định các quyền và khả năng đặc biệt được cấp bởi hệ thống của Apple. Đối với passkey, tệp này cấu hình Associated Domains.

Vị trí tệp: Thông thường trong dự án Xcode của bạn tại ios/Runner/Runner.entitlements

Triển khai gốc và Embedded WebView yêu cầu khả năng Associated Domains (Các miền liên kết) để liên kết ứng dụng với miền web của bạn. System WebView (ASWebAuthenticationSession) không yêu cầu điều này vì nó chạy trong bối cảnh Safari.

Thiết lập trong Xcode:

1. Mở dự án của bạn trong Xcode
2. Chọn target của ứng dụng
3. Chuyển đến tab "Signing & Capabilities"
4. Nhấp vào "+ Capability" và thêm "Associated Domains"
5. Thêm miền của bạn với tiền tố webcredentials:

Ví dụ Cấu hình:

<?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>

Nhiều miền: Nếu ứng dụng của bạn cần làm việc với nhiều miền, bạn có thể cần Related Origin Requests (ROR).

Android Embedded WebViews hỗ trợ passkey thông qua hai cách tiếp cận riêng biệt: cách tiếp cận dựa trên WebKit mới hơn (Phần 5.3.1) và cách tiếp cận cầu nối JavaScript (JavaScript bridge) cũ hơn (Phần 5.3.2). System WebView (Chrome Custom Tabs) không yêu cầu bất kỳ cấu hình nào-thông tin xác thực hoạt động tự động.

Android cung cấp các mẫu passkey WebView chính thức (official WebView passkey samples) trình diễn cả hai cách tiếp cận triển khai.

Tích hợp WebKit hiện đại với khả năng xử lý passkey gốc. Cách tiếp cận này cung cấp hỗ trợ WebAuthn gốc mà không yêu cầu mã cầu nối tùy chỉnh (custom bridge code).

Mẫu chính thức: Webkit WebView MainActivity

Yêu cầu:

• AndroidX WebKit 1.12.1 hoặc mới hơn (khuyên dùng 1.14.0+)
• Đã cấu hình Digital Asset Links
• APK WebView hỗ trợ WebAuthn (kiểm tra qua tính năng phát hiện - feature detection)
• Lưu ý: Thư viện AndroidX Credentials KHÔNG bắt buộc đối với WebView WebAuthn, chỉ dành cho các triển khai hoàn toàn gốc

Triển khai:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Kiểm tra xem Web Authentication có được hỗ trợ hay không
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Bật Web Authentication
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Bật JavaScript
    webView.settings.javaScriptEnabled = true
}

Điểm chính:

• Không cần cầu nối JavaScript: WebAuthn hoạt động nguyên bản trong WebView
• Yêu cầu phát hiện tính năng: Luôn kiểm tra WebViewFeature.WEB_AUTHENTICATION lúc chạy (runtime)
• Không hỗ trợ Conditional UI: mediation:"conditional" (tự động điền passkey trong các trường nhập liệu) không hoạt động trong Embedded WebView
• Chiến lược dự phòng: Nếu tính năng không khả dụng, hãy sử dụng Chrome Custom Tabs để thay thế

Lưu ý về phiên bản:

• Sử dụng WebKit 1.12.1 hoặc mới hơn (1.12.0 có vấn đề về tính khả dụng lúc chạy)
• Hỗ trợ tính năng phụ thuộc vào phiên bản APK WebView của người dùng - các APK cũ hơn trên thiết bị sẽ không tiết lộ tính năng

Trước AndroidX WebKit 1.12.0, hỗ trợ WebAuthn gốc không tồn tại trong Embedded WebView. Cách tiếp cận cũ hơn này sử dụng cầu nối Web-to-Native (Web-đến-Gốc) để xử lý passkey cho các thiết bị không có hỗ trợ WebAuthn của WebView gốc.

Mẫu chính thức:

• PasskeyWebListener (Trình xử lý cầu nối)
• Tiện ích mã hóa JavaScript

Khi nào nên sử dụng: Hỗ trợ các phiên bản Android cũ hơn hoặc các thiết bị có các bản triển khai WebView cũ.

Các nhóm phải:

1. Sử dụng Chrome Custom Tabs hoặc Auth Tab (được khuyến nghị)
2. Xây dựng một cầu nối JavaScript tùy chỉnh

Để biết chi tiết về cách triển khai, hãy xem Hướng dẫn tích hợp Credential Manager WebView của Android. Tuy nhiên, chúng tôi đặc biệt khuyên bạn nên sử dụng cách tiếp cận WebKit 1.12.1+ gốc cho các ứng dụng hiện đại.

Khuyến nghị: Sử dụng hỗ trợ WebAuthn gốc với AndroidX WebKit 1.12.1+. Nếu không khả dụng lúc chạy, hãy dự phòng về Chrome Custom Tabs, cung cấp hỗ trợ passkey rất tốt với thông tin xác thực dùng chung.

Khi triển khai passkey trong các ứng dụng gốc, bạn cần thiết lập sự tin cậy giữa ứng dụng và miền web của mình. Phần này đề cập đến cách xử lý các miền đơn lẻ, nhiều miền liên quan (ROR) và cách xác minh các tệp liên kết well-known của bạn được cấu hình chính xác.

Đối với các ứng dụng sử dụng miền đơn lẻ (ví dụ: kayak.com), bạn cần:

• Một tệp AASA cho iOS tại https://kayak.com/.well-known/apple-app-site-association
• Một tệp assetlinks.json cho Android tại https://kayak.com/.well-known/assetlinks.json
• Entitlement Associated Domains được cấu hình với webcredentials:kayak.com

Related Origins (ROR) là một tính năng của WebAuthn cho phép một bộ passkey duy nhất hoạt động trên nhiều miền liên quan (ví dụ: kayak.com, kayak.de, kayak.co.uk). ROR sử dụng endpoint /.well-known/webauthn trên mỗi trang web để định nghĩa các nguồn (origins) liên quan, KHÔNG phải các tệp AASA hoặc assetlinks.

Điểm chính:

• Cấu hình ROR: Mỗi miền lưu trữ /.well-known/webauthn với danh sách các nguồn liên quan
• Các tệp liên kết ứng dụng (AASA/assetlinks): Chỉ được sử dụng để ánh xạ các ứng dụng với các trang web tương ứng của chúng
• iOS 18+ Embedded WebView: Hỗ trợ ROR khi được cấu hình đúng
• Entitlements Associated Domains: Bao gồm tất cả các miền mà ứng dụng của bạn cần xác thực

Ví dụ Cấu hình:

Nếu ứng dụng của bạn hoạt động với kayak.com và kayak.de, cả hai miền phải:

• Lưu trữ các tệp AASA tương ứng với cùng một Team ID và Bundle ID
• Được liệt kê trong entitlements Associated Domains của ứng dụng của bạn
• Có các tệp well-known được cấu hình đúng và có thể truy cập

Trước khi đi vào hoạt động thực tế, hãy xác minh rằng các tệp well-known của bạn đã được cấu hình đúng và có thể truy cập được. Apple và Google cung cấp các URL thử nghiệm dựa trên CDN để kiểm tra tính khả dụng của tệp:

Sử dụng Các URL Thử nghiệm này:

• Nhấp vào các liên kết để xác minh xem Apple/Google có thể truy xuất các tệp well-known của bạn hay không
• Tham số ?nocache=1 của Apple buộc truy xuất mới, bỏ qua bộ nhớ đệm CDN
• Nếu các tệp không thể truy cập thông qua các URL này, chức năng passkey sẽ không hoạt động trong ứng dụng của bạn
• Thay thế kayak.com hoặc kayak.de bằng (các) miền của riêng bạn trong các mẫu URL ở trên

Lưu ý khi Thử nghiệm: Đảm bảo tất cả các miền đều có các tệp well-known được cấu hình đúng. Một tệp bị thiếu hoặc cấu hình sai trên bất kỳ miền nào đều có thể làm hỏng chức năng passkey cho miền đó.

Thêm Thông tin: Relying Party ID của WebAuthn trong Các ứng dụng Gốc

Việc chọn cách tiếp cận triển khai phù hợp phụ thuộc vào kiến trúc xác thực, yêu cầu OAuth của ứng dụng và nhu cầu kiểm soát phiên. Sử dụng cây quyết định này để xác định hướng đi tốt nhất.

Lưu đồ sau đây hướng dẫn bạn chọn cách tiếp cận triển khai phù hợp dựa trên các yêu cầu của ứng dụng:

Tham khảo nhanh cho từng hướng đi:

• Đăng nhập dựa trên OAuth? → System WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• Tái sử dụng xác thực web trong vỏ gốc? → Embedded WebView với cấu hình (WKWebView / Android WebView + WebKit 1.12.1+)
• Xây dựng ưu tiên gốc? → Triển khai Gốc (AuthenticationServices / Credential Manager)
• Xác thực web hiện có để tái sử dụng? → System WebView để triển khai nhanh chóng; nếu không thì Gốc cho UX tối ưu

Dưới đây là cách mỗi cách tiếp cận thực hiện trên các khía cạnh chính:

Giải thích các khía cạnh:

• Tạo Passkey: Người dùng có thể tạo passkey dễ dàng như thế nào thông qua cách tiếp cận này
• Sử dụng Passkey: Trải nghiệm xác thực khi sử dụng các passkey hiện có
• Quản lý Passkey: Người dùng xem, chỉnh sửa hoặc xóa passkey như thế nào
• Độ phức tạp kỹ thuật: Nỗ lực phát triển và bảo trì liên tục
• Hỗ trợ OAuth: Cách tiếp cận này xử lý các luồng xác thực OAuth2/OIDC tốt như thế nào
• Thời gian Thiết lập: Thời gian triển khai điển hình

Khuyến nghị: System WebView

Nếu ứng dụng của bạn xác thực qua OAuth2, OIDC hoặc các nhà cung cấp đăng nhập mạng xã hội (Google, GitHub, Microsoft, v.v.), System WebView là lựa chọn tối ưu:

• iOS: ASWebAuthenticationSession được xây dựng có mục đích cho các luồng OAuth
• Android: Chrome Custom Tabs cung cấp tích hợp OAuth liền mạch
• Lợi ích: Mã gốc tối thiểu, tự động chia sẻ thông tin xác thực
• Triển khai: Thêm WebAuthn vào trang xác thực web của bạn, sau đó tải nó thông qua System WebView

Ví dụ: Các ứng dụng du lịch như kayak.com và kayak.de sử dụng OAuth để xác thực. System WebView cho phép chúng duy trì cơ sở hạ tầng OAuth hiện có trong khi thêm hỗ trợ passkey thông qua các trang xác thực web của chúng.

Khuyến nghị: Cách tiếp cận Lai

Sử dụng System WebView cho xác thực OAuth ban đầu, sau đó là Embedded WebView cho các phiên sau xác thực:

1. Xác thực Ban đầu: System WebView xử lý đăng nhập OAuth + passkey
2. Quản lý Phiên: Chuyển sang Embedded WebView cho nội dung web đã xác thực nơi bạn cần kiểm soát cookie/phiên
3. Thiết lập Kỹ thuật: Cấu hình cả yêu cầu System và Embedded WebView - đối với Android, đảm bảo bao gồm AndroidX WebKit 1.12.1+ (xem Phần 5)

Khi nào nên sử dụng: Các ứng dụng xác thực qua OAuth nhưng sau đó cần hiển thị nội dung web đã xác thực, nơi cần có thao tác phiên trực tiếp.

Khuyến nghị: Triển khai Gốc

Xây dựng từ đầu hoặc có các màn hình gốc? Hãy xây dựng hoàn toàn gốc:

• iOS: Sử dụng framework AuthenticationServices
• Android: Sử dụng API Credential Manager
• Lợi ích: UX tốt nhất, xác thực tức thì, kiểm soát hoàn toàn
• Lợi thế Độc nhất: Sử dụng preferImmediatelyAvailableCredentials để hiển thị lớp phủ passkey tự động khi khởi động ứng dụng - độc quyền cho các triển khai gốc và cung cấp tỷ lệ chuyển đổi cao nhất
• Khuyến nghị về SDK: Sử dụng SDK Corbado (iOS, Android) để tăng tốc phát triển với khả năng xử lý các trường hợp ngoại lệ đã được thử nghiệm thực tế

Đối với Các ứng dụng Mới: Đặc biệt khuyến nghị xây dựng đăng nhập gốc ngay từ ngày đầu tiên. Thiết lập cho bạn UX tối ưu và tránh các đợt di chuyển từ WebView sang gốc trong tương lai.

Khuyến nghị: Di chuyển theo Giai đoạn

Biểu đồ sau đây cho thấy lộ trình di chuyển tăng dần:

Mỗi giai đoạn được xây dựng dựa trên giai đoạn trước, cho phép cải thiện dần dần mà không làm gián đoạn người dùng hiện có.

Xem Phần 5 để biết hướng dẫn cấu hình chi tiết.

Việc thử nghiệm passkey trong các ứng dụng gốc yêu cầu một cách tiếp cận có cấu trúc, nhiều lớp. Tuân theo kim tự tháp thử nghiệm: thử nghiệm đơn vị (logic cô lập), thử nghiệm tích hợp (WebAuthn ceremony trên trình mô phỏng/emulator) và thử nghiệm hệ thống (đầu cuối - end-to-end trên thiết bị vật lý).

Các Danh mục Thử nghiệm Thiết yếu:

• Các Hành trình Cốt lõi: Đăng ký, xác thực, luồng đa thiết bị, xóa passkey
• Mức độ bao phủ Nền tảng: iOS (gốc), Android (gốc), trình duyệt web trên các phiên bản OS
• Liên kết Miền: Xác minh tệp AASA (iOS) và Digital Asset Links (Android) có thể truy cập được
• Luồng Hủy: Thử nghiệm việc người dùng hủy tại các lời nhắc của OS và màn hình sinh trắc học
• Xử lý Lỗi: Backend lỗi, hết thời gian mạng, thông tin xác thực không khớp
• Trường hợp Ngoại lệ: Khóa màn hình bị tắt, iCloud/Google Password Manager bị tắt
• Luồng OAuth: Tích hợp hoàn chỉnh OAuth + passkey đầu cuối
• Thiết bị được Quản lý: Môi trường do MDM kiểm soát (xem thử nghiệm thiết bị được quản lý)
• Trình quản lý Bên thứ ba: Khả năng tương thích 1Password, Bitwarden, Dashlane
• Xác thực Đa thiết bị: Luồng mã QR và thử nghiệm truyền tải lai
• Đặc thù Embedded WebView: Nếu sử dụng Embedded WebView, hãy xác minh cấu hình WebKit 1.12.1+ trên Android
• Giám sát Sản xuất: Bảng điều khiển cho tỷ lệ thành công, thất bại và độ trễ

Để biết hướng dẫn thử nghiệm toàn diện bao gồm các chiến lược tự động hóa, những điều cần chú ý cho từng nền tảng và danh sách kiểm tra đầy đủ trước khi chạy, hãy xem hướng dẫn dành riêng của chúng tôi: Thử nghiệm Luồng Passkey trong Các Ứng dụng Gốc iOS & Android.

Xem xét nhắc người dùng tạo passkey sau khi đăng nhập truyền thống thành công (mật khẩu, OAuth). Cách tiếp cận chuyển đổi dần dần này:

• Không làm gián đoạn các luồng xác thực hiện có
• Cho phép xuống cấp một cách nhẹ nhàng (graceful degradation) nếu người dùng từ chối
• Tăng cường áp dụng passkey theo thời gian mà không ép buộc thay đổi
• Hoạt động tốt với cả ba cách tiếp cận triển khai

Ví dụ: Sau khi đăng nhập OAuth qua System WebView, hiển thị một lời nhắc gốc: "Bật đăng nhập nhanh hơn với Face ID?" Nếu được chấp nhận, hãy tạo passkey thông qua trang web được tải trong System WebView.

Quyết định cách triển khai passkey - qua Triển khai Gốc, System WebView hay Embedded WebView là một lựa chọn thiết kế quan trọng tác động đến bảo mật, trải nghiệm người dùng và độ phức tạp trong phát triển. Không có câu trả lời nào phù hợp cho tất cả (one-size-fits-all).

Đối với các ứng dụng dựa trên OAuth: System WebView (ASWebAuthenticationSession, Chrome Custom Tabs) là điểm khởi đầu được khuyến nghị. Nó cung cấp hỗ trợ OAuth tuyệt vời, nỗ lực triển khai tối thiểu và tự động chia sẻ thông tin xác thực.

Đối với các ứng dụng ưu tiên gốc: Hãy đi theo hướng gốc càng sớm càng tốt. Đăng nhập passkey gốc cung cấp UX liền mạch nhất với các khả năng độc quyền như preferImmediatelyAvailableCredentials, kích hoạt lớp phủ passkey tự động khi khởi động ứng dụng - điều mà các triển khai WebView không thể cung cấp. Với việc iOS và Android hiện cung cấp hỗ trợ hạng nhất cho passkey, những thành công trong thế giới thực chứng tỏ mức độ áp dụng cao. Các công cụ (bao gồm SDK mã nguồn mở và thư viện nền tảng) đã trưởng thành để làm cho việc tích hợp gốc có thể đạt được trong khung thời gian hợp lý. Mặc dù bạn phải lưu ý đến các chính sách quản lý thiết bị, đồng bộ hóa giữa các thiết bị và các nhà cung cấp bên thứ ba, những thách thức này có thể được quản lý bằng kỹ thuật và thử nghiệm cẩn thận. Kết quả là một ứng dụng đăng nhập làm hài lòng người dùng với sự dễ dàng và tốc độ đồng thời cải thiện đáng kể khả năng bảo mật.

Đối với yêu cầu về khung WebView nhúng: Embedded WebView thường được sử dụng trong hai tình huống thực tế. Thứ nhất, các ứng dụng dựa trên OAuth thường sử dụng System WebView cho luồng đăng nhập ban đầu, sau đó chuyển sang Embedded WebView để hiển thị các tùy chọn quản lý passkey trong màn hình cài đặt, nơi cần có sự kiểm soát phiên - mặc dù một số ứng dụng đơn giản hóa điều này bằng cách giữ nguyên System WebView cho cả hai luồng. Thứ hai, các ứng dụng đã nhúng luồng xác thực của họ vào khung WebView trước khi áp dụng passkey tiếp tục mô hình này để đảm bảo tính nhất quán. Embedded WebView với hỗ trợ WebAuthn gốc (AndroidX WebKit 1.12.1+) yêu cầu cấu hình và thiết lập (quyền, entitlements, cài đặt WebView) nhưng không còn cần mã cầu nối JavaScript tùy chỉnh nữa. Lưu ý rằng Conditional UI không được hỗ trợ trong Embedded WebView. Chọn cách tiếp cận này khi duy trì các mẫu xác thực nhúng hiện có hoặc khi bạn cần kiểm soát phiên/cookie cho các màn hình sau xác thực.

Cuối cùng, passkey trong các ứng dụng gốc thể hiện một bước tiến lớn về cả sự tiện lợi cho người dùng và tính bảo mật. Cho dù được triển khai qua Triển khai Gốc, System WebView hay Embedded WebView, chúng đều loại bỏ rủi ro lừa đảo và gánh nặng quản lý mật khẩu đối với người dùng của bạn. Việc triển khai thực tế như tích hợp passkey trong ứng dụng gốc của VicRoads cho thấy rằng các cách tiếp cận ưu tiên gốc mang lại mức độ áp dụng và sự hài lòng cao nhất của người dùng khi được thực hiện đúng cách với các tính năng như lớp phủ passkey tự động. Bằng cách làm theo các phương pháp hay nhất cho xác thực thân thiện với người dùng và chọn cách tiếp cận triển khai phù hợp với kiến trúc của ứng dụng - ưu tiên gốc cho các ứng dụng mới, System WebView cho các luồng OAuth, hoặc Embedded WebView cho các mẫu nhúng hiện có - bạn có thể cung cấp tính năng đăng nhập không cần mật khẩu, sinh trắc học nhằm hiện thực hóa tầm nhìn về passkey: xác thực đơn giản, an toàn và thú vị cho mọi người.

Nếu passkey không hoạt động trong ứng dụng gốc của bạn, hãy kiểm tra các sự cố phổ biến này theo cách tiếp cận triển khai:

• Các tệp được phục vụ qua HTTPS với chứng chỉ hợp lệ
• Kiểu MIME chính xác: application/json
• Không có chuyển hướng trên đường dẫn .well-known
• iOS: Team ID và Bundle ID khớp chính xác trong tệp AASA
• Android: Dấu vân tay SHA256 khớp với chứng chỉ ký của bạn trong assetlinks.json
• Relying Party ID khớp với miền của bạn (không có giao thức, không có cổng)
• Không có dấu gạch chéo cuối trong RP ID
• WebAuthn origin: https://your-domain.com (không phải app://)

• iOS: Khả năng Associated Domains được bật trong Xcode với webcredentials:yourdomain.com
• Android: Digital Asset Links được khai báo trong AndroidManifest.xml
• Người dùng đã bật khóa màn hình (sinh trắc học hoặc PIN)
• Thử nghiệm với AASA Validator của Apple và công cụ Digital Asset Links của Google
• Xác minh tệp Runner.entitlements chứa các miền liên kết chính xác

• iOS: Sử dụng ASWebAuthenticationSession (khuyên dùng) hoặc SFSafariViewController
• Android: Sử dụng Chrome Custom Tabs (không phải WebView thuần túy)
• iOS: Xác minh Associated Domains đã được cấu hình nếu cần
• Kiểm tra xem cookie/thông tin xác thực có được chia sẻ với trình duyệt hệ thống không
• Xác minh trang xác thực web có bản triển khai WebAuthn phù hợp

• iOS: Được cấu hình với các entitlements phù hợp
• iOS: Associated Domains bao gồm tất cả các miền có liên quan
• iOS: Tệp AASA có thể truy cập và được định dạng đúng
• iOS: Thử nghiệm với ?mode=developer trong quá trình phát triển (loại bỏ đối với sản xuất)
• Android: AndroidX WebKit 1.12.1+ (hoặc mới hơn) có trong dự án
• Android: Kiểm tra tính năng lúc chạy đối với WebViewFeature.WEB_AUTHENTICATION
• Android: Gọi setWebAuthenticationSupport() với WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: Đã bật JavaScript trong cài đặt WebView
• Android: Phiên bản APK WebView của người dùng hỗ trợ tính năng WebAuthn (sử dụng phát hiện tính năng, không phải phiên bản hệ điều hành)
• Không sử dụng Conditional UI (không được hỗ trợ trong Embedded WebView)
• Dự phòng về Chrome Custom Tabs nếu tính năng WebAuthn không khả dụng

• Kiểm tra xem người dùng có nhà cung cấp thông tin xác thực phi mặc định đang hoạt động không (1Password, Bitwarden, v.v.)
• Xác minh nhà cung cấp hỗ trợ passkey (không phải tất cả các trình quản lý mật khẩu đều hỗ trợ)
• Thử nghiệm với trình quản lý thông tin xác thực gốc của nền tảng (iCloud Keychain, Google Password Manager)

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

• Thường có nghĩa là: Thiếu entitlements (iOS) hoặc tính năng WebView không khả dụng/chưa được bật (Android Embedded WebView)
• Kiểm tra: Cấu hình Associated Domains, khả năng truy cập tệp AASA, phiên bản WebKit, phát hiện tính năng, lệnh gọi setWebAuthenticationSupport()

Không có lời nhắc passkey xuất hiện

• Có thể có nghĩa là: AASA/assetlinks.json không tải, sai loại WebView, tệp AASA bị lưu trong bộ nhớ cache
• Thử: Xác thực các tệp liên kết, sử dụng ?mode=developer trên iOS để thử nghiệm, xác minh loại WebView

Để biết gỡ lỗi chi tiết, hãy xem bài viết của chúng tôi về Relying Party IDs trong các ứng dụng gốc.

Một cạm bẫy phổ biến: môi trường staging có quyền truy cập hạn chế (IP whitelisting, chỉ dùng VPN) sẽ thất bại vì các CDN của Apple và Google phải có thể lấy được các tệp liên kết của bạn.

• Tệp AASA/assetlinks có thể truy cập công khai (không có IP whitelisting, không có yêu cầu VPN)
• Xác minh CDN của Apple có thể truy cập tệp của bạn: https://app-site-association.cdn-apple.com/a/v1/your-staging-domain.com?nocache=1
• Xác minh Google có thể truy cập tệp của bạn: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://your-staging-domain.com&relation=delegate_permission/common.handle_all_urls

Staging subdomain với rpID sản xuất:

Nếu môi trường staging của bạn (ví dụ: stg.login.example.com) sử dụng miền sản xuất làm rpID (ví dụ: example.com), quá trình tra cứu AASA sẽ diễn ra trên miền rpID, chứ không phải staging subdomain của bạn. Điều này có nghĩa là:

• Thêm các ID bundle của ứng dụng staging vào tệp AASA sản xuất của bạn
• Lưu ý rằng passkey được tạo trong staging sẽ xuất hiện trong các luồng đăng nhập sản xuất (có khả năng gây nhầm lẫn)

Ví dụ (nhiều môi trường chia sẻ một AASA):

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

Khuyến nghị: Sử dụng một rpID staging riêng khớp với miền staging của bạn để tránh chồng chéo thông tin xác thực giữa các môi trường. Điều này yêu cầu các tệp AASA có thể truy cập công khai trên miền staging.

Làm rõ về ?mode=developer:

Tham số ?mode=developer trong Associated Domains bỏ qua bộ nhớ đệm CDN của Apple nhưng không bỏ qua yêu cầu về khả năng truy cập. Tệp AASA của bạn vẫn phải có thể truy cập được từ thiết bị (không thông qua CDN của Apple mà trực tiếp). Điều này giúp trong quá trình phát triển khi lặp lại các thay đổi AASA, nhưng sẽ không giúp ích nếu máy chủ staging của bạn nằm trong danh sách IP whitelist.

SDK Gốc của Corbado:

• SDK iOS (Swift)
• SDK Android (Kotlin)
• Gói Flutter

Tài liệu Nền tảng:

• Apple: Hỗ trợ Passkey
• Google: Credential Manager

Công cụ Xác thực:

• Apple AASA Validator
• Trình tạo Google Digital Asset Links

Về Corbado

Corbado là Passkey Intelligence Platform dành cho các đội CIAM vận hành xác thực consumer ở quy mô lớn. Chúng tôi giúp bạn nhìn thấy điều mà log IDP và các công cụ analytics thông thường không thấy: những thiết bị, phiên bản OS, trình duyệt và trình quản lý credential nào hỗ trợ passkey, tại sao quá trình đăng ký không chuyển thành đăng nhập, luồng WebAuthn fail ở đâu, và khi nào một bản cập nhật OS hay trình duyệt làm hỏng đăng nhập một cách âm thầm — tất cả mà không cần thay thế Okta, Auth0, Ping, Cognito hay IDP nội bộ của bạn. Hai sản phẩm: Corbado Observe bổ sung observability cho passkey và mọi phương thức đăng nhập khác. Corbado Connect mang đến managed passkey với analytics tích hợp (song hành cùng IDP của bạn). VicRoads vận hành passkey cho hơn 5M người dùng với Corbado (kích hoạt passkey +80%). Trao đổi với chuyên gia Passkey →

Sự lựa chọn phụ thuộc vào kiến trúc xác thực của bạn. Nếu ứng dụng của bạn sử dụng OAuth2 hoặc OIDC, System WebView (ASWebAuthenticationSession trên iOS hoặc Chrome Custom Tabs trên Android) yêu cầu nỗ lực triển khai thấp nhất và không cần thiết lập tệp liên kết. Đối với các ứng dụng ưu tiên gốc mới, Triển khai Gốc cung cấp UX vượt trội, trong khi Embedded WebView phù hợp với các ứng dụng đã nhúng xác thực trong khung WebView và cần kiểm soát phiên hoặc cookie sau khi đăng nhập.

SFSafariViewController tận dụng công cụ của Safari, hiển thị thanh URL với các chỉ báo SSL và cung cấp khả năng bảo vệ khỏi lừa đảo, làm cho nó đáng tin cậy hơn đối với các luồng xác thực. WKWebView cung cấp nhiều khả năng tùy chỉnh UI hơn nhưng có kho lưu trữ cookie bị cô lập tách biệt khỏi Safari, yêu cầu entitlements Associated Domains và tệp AASA để bật passkey, và không hiển thị thanh URL, làm giảm các tín hiệu tin cậy của người dùng.

Chrome Custom Tabs chia sẻ cookie và thông tin xác thực đã lưu với trình duyệt Chrome của người dùng, có nghĩa là các passkey được lưu trong Google Password Manager có thể được truy cập trong quá trình xác thực. Android WebView tiêu chuẩn có kho lưu trữ cookie bị cô lập, không hiển thị URL hoặc các chỉ báo SSL và Google đã cấm rõ ràng việc sử dụng nó đối với các lượt đăng nhập tài khoản Google do rủi ro lừa đảo.

Nếu người dùng có trình quản lý thông tin xác thực của bên thứ ba như 1Password được thiết lập làm nhà cung cấp đang hoạt động của họ, nó thường sẽ can thiệp vào việc tạo và lưu trữ passkey, ưu tiên hơn trình quản lý thông tin xác thực gốc của nền tảng (iCloud Keychain hoặc Google Password Manager). Điều này có nghĩa là passkey có thể được lưu trữ trong ứng dụng của bên thứ ba thay vì keychain của nền tảng, ảnh hưởng đến hành vi đồng bộ hóa giữa các thiết bị và quản lý passkey.

Khi các chính sách MDM vô hiệu hóa đồng bộ hóa thông tin xác thực, passkey trở nên bị giới hạn vào thiết bị và không thể chuyển vùng đến thiết bị thay thế, không giống như các tình huống tiêu dùng điển hình. Các ứng dụng nhắm mục tiêu đến môi trường doanh nghiệp nên lập kế hoạch cho các cơ chế xác thực dự phòng như đăng nhập bằng mật khẩu hoặc liên kết ma thuật để xử lý các trường hợp người dùng nhận được thiết bị được quản lý mới.