Trình quản lý thông tin xác thực là một API Jetpack hỗ trợ nhiều phương thức đăng nhập, chẳng hạn như đăng nhập bằng tên người dùng và mật khẩu, khoá truy cập và các giải pháp đăng nhập được liên kết (chẳng hạn như Đăng nhập bằng Google) trong một API duy nhất, từ đó đơn giản hoá quá trình tích hợp cho nhà phát triển.
Hơn nữa, đối với người dùng, Trình quản lý thông tin xác thực sẽ hợp nhất giao diện đăng nhập trên các phương thức xác thực, giúp người dùng đăng nhập vào ứng dụng một cách rõ ràng và dễ dàng hơn, bất kể họ chọn phương thức nào.
Trang này giải thích khái niệm khoá truy cập và các bước triển khai việc hỗ trợ ở phía máy khách cho các giải pháp xác thực (bao gồm cả khoá truy cập) bằng cách sử dụng Credential Manager API. Ngoài ra, bạn cũng có thể truy cập vào một trang Câu hỏi thường gặp riêng để tìm câu trả lời cho những câu hỏi cụ thể và chi tiết hơn.
Ý kiến phản hồi của bạn có vai trò quan trọng trong việc cải thiện Credential Manager API. Hãy chia sẻ mọi vấn đề bạn phát hiện được hoặc các ý tưởng giúp cải thiện API bằng đường liên kết sau:
Giới thiệu về khoá truy cập
Khoá truy cập là phương thức thay thế an toàn và dễ dàng hơn cho mật khẩu. Với khoá truy cập, người dùng có thể đăng nhập vào các ứng dụng và trang web nhờ cảm biến sinh trắc học (chẳng hạn như dùng vân tay hoặc công nghệ nhận dạng khuôn mặt), mã PIN hoặc hình mở khoá. Khoá truy cập này mang lại trải nghiệm đăng nhập liền mạch, giúp người dùng không phải nhớ tên người dùng hoặc mật khẩu.
Khoá truy cập dựa vào WebAuthn (Ứng dụng xác thực người dùng truy cập Internet), một tiêu chuẩn do Liên minh FIDO và tổ chức the World Wide Web Consortium (W3C) cùng phát triển. WebAuthn sử dụng tiêu chuẩn mã hoá khoá công khai để xác thực người dùng. Trang web hoặc ứng dụng mà người dùng đăng nhập vào có thể xem và lưu trữ khoá công khai, nhưng tuyệt đối không nhận được khoá riêng tư. Khoá riêng tư này được giữ bí mật và an toàn. Chính vì khoá này là duy nhất cũng như gắn liền với trang web hoặc ứng dụng, nên khoá truy cập sẽ không thể đánh cắp được, nhờ đó tăng cường bảo mật.
Người dùng có thể sử dụng Trình quản lý thông tin xác thực để tạo khoá truy cập và lưu trữ các khoá đó trong Trình quản lý mật khẩu của Google.
Hãy đọc bài viết Xác thực người dùng bằng khoá truy cập để biết hướng dẫn về cách triển khai quy trình xác thực khoá truy cập liền mạch bằng Trình quản lý thông tin xác thực.
Điều kiện tiên quyết
Để sử dụng Trình quản lý thông tin xác thực, hãy hoàn thành các bước trong phần này.
Sử dụng phiên bản nền tảng gần đây
Hỗ trợ Trình quản lý thông tin xác thực trên Android 4.4 (API cấp 19) trở lên.
Thêm phần phụ thuộc vào ứng dụng
Thêm các phần phụ thuộc sau đây vào tập lệnh bản dựng của mô-đun ứng dụng:
Kotlin
dependencies { implementation("androidx.credentials:credentials:1.5.0-beta01") // optional - needed for credentials support from play services, for devices running // Android 13 and below. implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.5.0-beta01" // optional - needed for credentials support from play services, for devices running // Android 13 and below. implementation "androidx.credentials:credentials-play-services-auth:1.5.0-beta01" }
Giữ nguyên các lớp trong tệp ProGuard
Trong tệp proguard-rules.pro của mô-đun, hãy thêm các lệnh sau:
-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
*;
}
Tìm hiểu thêm về cách rút gọn, làm rối mã nguồn và tối ưu hoá ứng dụng.
Thêm tính năng hỗ trợ cho Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số)
Để bật tính năng hỗ trợ khoá truy cập cho ứng dụng Android, hãy liên kết ứng dụng của bạn với một trang web mà ứng dụng đó sở hữu. Bạn có thể khai báo mối liên kết này bằng cách hoàn thành các bước sau:
Tạo tệp JSON chứa Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số). Ví dụ: để khai báo rằng trang web
https://signin.example.comvà ứng dụng Android có tên góicom.examplecó thể dùng chung thông tin đăng nhập, hãy tạo một tệp có tênassetlinks.jsonvới nội dung sau:[ { "relation" : [ "delegate_permission/common.handle_all_urls", "delegate_permission/common.get_login_creds" ], "target" : { "namespace" : "android_app", "package_name" : "com.example.android", "sha256_cert_fingerprints" : [ SHA_HEX_VALUE ] } } ]Trường
relationlà một mảng gồm một hoặc nhiều chuỗi mô tả mối quan hệ đang được khai báo. Để khai báo rằng các ứng dụng và trang web dùng chung thông tin đăng nhập, hãy chỉ định các mối quan hệ làdelegate_permission/handle_all_urlsvàdelegate_permission/common.get_login_creds.Trường
targetlà đối tượng chỉ định tài sản mà nội dung khai báo sẽ áp dụng. Sau đây là các trường xác định một trang web:namespacewebsiteURL của trang web, có định dạng
https://domain[:optional_port]; ví dụ:https://www.example.com.domain phải đủ điều kiện và phải bỏ qua optional_port khi sử dụng cổng 443 cho HTTPS.
Đích
sitechỉ được là miền gốc: bạn không thể giới hạn liên kết ứng dụng với một thư mục con cụ thể. Đừng thêm một đường dẫn vào URL, chẳng hạn như dấu gạch chéo ở cuối.Miền con không được cân nhắc để khớp: nghĩa là nếu bạn chỉ định domain là
www.example.com, thì miềnwww.counter.example.comsẽ không được liên kết với ứng dụng của bạn.Sau đây là các trường xác định một ứng dụng Android:
namespaceandroid_apppackage_nameTên gói được khai báo trong tệp kê khai của ứng dụng. Ví dụ: com.example.androidsha256_cert_fingerprintsCác vân tay số SHA256 trong chứng chỉ ký của ứng dụng. Lưu trữ tệp JSON chứa Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số) tại vị trí sau trên miền đăng nhập:
https://domain[:optional_port]/.well-known/assetlinks.jsonVí dụ: nếu miền đăng nhập của bạn là
signin.example.com, hãy lưu trữ tệp JSON tạihttps://signin.example.com/.well-known/assetlinks.json.Loại MIME cho tệp Digital Asset Link (Đường liên kết đến tài sản kỹ thuật số) phải là JSON. Hãy đảm bảo máy chủ gửi một tiêu đề
Content-Type: application/jsontrong phản hồi.Đảm bảo rằng máy chủ lưu trữ cho phép Google truy xuất tệp Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số) của bạn. Nếu bạn có tệp
robots.txt, tệp đó phải cho phép tác nhân Googlebot truy xuất/.well-known/assetlinks.json. Hầu hết các trang web có thể cho phép mọi tác nhân tự động hoá truy xuất tệp trong đường dẫn/.well-known/để các dịch vụ khác có thể truy cập vào siêu dữ liệu trong những tệp đó:User-agent: * Allow: /.well-known/Thêm dòng sau vào tệp kê khai trong
<application>:<meta-data android:name="asset_statements" android:resource="@string/asset_statements" />Nếu bạn đang dùng tính năng đăng nhập bằng mật khẩu thông qua Trình quản lý thông tin xác thực, hãy làm theo bước này để định cấu hình việc liên kết đến tài sản kỹ thuật số trong tệp kê khai. Nếu chỉ sử dụng khoá truy cập, bạn không cần phải thực hiện bước này.
Khai báo mối liên kết trong ứng dụng Android. Thêm một đối tượng chỉ định các tệp
assetlinks.jsoncần tải. Bạn phải thoát khỏi mọi dấu nháy đơn và dấu ngoặc kép mà bạn dùng trong chuỗi. Ví dụ:<string name="asset_statements" translatable="false"> [{ \"include\": \"https://signin.example.com/.well-known/assetlinks.json\" }] </string>> GET /.well-known/assetlinks.json HTTP/1.1 > User-Agent: curl/7.35.0 > Host: signin.example.com < HTTP/1.1 200 OK < Content-Type: application/json
Định cấu hình Trình quản lý thông tin xác thực
Để định cấu hình và khởi tạo đối tượng CredentialManager, hãy thêm logic tương tự như sau:
Kotlin
// Use your app or activity context to instantiate a client instance of // CredentialManager. val credentialManager = CredentialManager.create(context)
Java
// Use your app or activity context to instantiate a client instance of // CredentialManager. CredentialManager credentialManager = CredentialManager.create(context)
Chỉ báo trường thông tin đăng nhập
Trên Android 14 trở lên, bạn có thể dùng thuộc tính isCredential để chỉ báo trường thông tin đăng nhập, chẳng hạn như trường tên người dùng hoặc mật khẩu. Thuộc tính này cho biết rằng thành phần hiển thị này là một trường thông tin đăng nhập sẽ hoạt động với Trình quản lý thông tin xác thực và nhà cung cấp thông tin đăng nhập bên thứ ba, đồng thời giúp các dịch vụ tự động điền cung cấp nội dung gợi ý tự động điền hiệu quả hơn. Khi ứng dụng sử dụng API Trình quản lý thông tin xác thực, bảng dưới cùng của Trình quản lý thông tin xác thực có thông tin đăng nhập sẽ xuất hiện, và tính năng tự động điền không cần hiện hộp thoại điền tên người dùng hoặc mật khẩu nữa. Tương tự như vậy, bạn không cần hiển thị hộp thoại lưu mật khẩu của tính năng tự động điền, vì ứng dụng sẽ yêu cầu Credential Manager API lưu thông tin xác thực.
Để sử dụng thuộc tính isCredential, hãy thêm thuộc tính này vào các Thành phần hiển thị liên quan:
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:isCredential="true"
...
/>
Đăng nhập người dùng
Để truy xuất mọi tuỳ chọn mật khẩu và khoá truy cập được liên kết với tài khoản của người dùng, hãy hoàn tất các bước sau:
Khởi tạo các tuỳ chọn xác thực bằng mật khẩu và khoá truy cập:
Kotlin
// Retrieves the user's saved password for your app from their // password provider. val getPasswordOption = GetPasswordOption() // Get passkey from the user's public key credential provider. val getPublicKeyCredentialOption = GetPublicKeyCredentialOption( requestJson = requestJson )
Java
// Retrieves the user's saved password for your app from their // password provider. GetPasswordOption getPasswordOption = new GetPasswordOption(); // Get passkey from the user's public key credential provider. GetPublicKeyCredentialOption getPublicKeyCredentialOption = new GetPublicKeyCredentialOption(requestJson);
Sử dụng các lựa chọn được truy xuất từ bước trước đây để tạo yêu cầu đăng nhập.
Kotlin
val getCredRequest = GetCredentialRequest( listOf(getPasswordOption, getPublicKeyCredentialOption) )
Java
GetCredentialRequest getCredRequest = new GetCredentialRequest.Builder() .addCredentialOption(getPasswordOption) .addCredentialOption(getPublicKeyCredentialOption) .build();
Khởi động quy trình đăng nhập:
Kotlin
coroutineScope.launch { try { val result = credentialManager.getCredential( // Use an activity-based context to avoid undefined system UI // launching behavior. context = activityContext, request = getCredRequest ) handleSignIn(result) } catch (e : GetCredentialException) { handleFailure(e) } } fun handleSignIn(result: GetCredentialResponse) { // Handle the successfully returned credential. val credential = result.credential when (credential) { is PublicKeyCredential -> { val responseJson = credential.authenticationResponseJson // Share responseJson i.e. a GetCredentialResponse on your server to // validate and authenticate } is PasswordCredential -> { val username = credential.id val password = credential.password // Use id and password to send to your server to validate // and authenticate } is CustomCredential -> { // If you are also using any external sign-in libraries, parse them // here with the utility functions provided. if (credential.type == ExampleCustomCredential.TYPE) { try { val ExampleCustomCredential = ExampleCustomCredential.createFrom(credential.data) // Extract the required credentials and complete the authentication as per // the federated sign in or any external sign in library flow } catch (e: ExampleCustomCredential.ExampleCustomCredentialParsingException) { // Unlikely to happen. If it does, you likely need to update the dependency // version of your external sign-in library. Log.e(TAG, "Failed to parse an ExampleCustomCredential", e) } } else { // Catch any unrecognized custom credential type here. Log.e(TAG, "Unexpected type of credential") } } else -> { // Catch any unrecognized credential type here. Log.e(TAG, "Unexpected type of credential") } } }
Java
credentialManager.getCredentialAsync( // Use activity based context to avoid undefined // system UI launching behavior activity, getCredRequest, cancellationSignal, <executor>, new CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() { @Override public void onResult(GetCredentialResponse result) { handleSignIn(result); } @Override public void onError(GetCredentialException e) { handleFailure(e); } } ); public void handleSignIn(GetCredentialResponse result) { // Handle the successfully returned credential. Credential credential = result.getCredential(); if (credential instanceof PublicKeyCredential) { String responseJson = ((PublicKeyCredential) credential).getAuthenticationResponseJson(); // Share responseJson i.e. a GetCredentialResponse on your server to validate and authenticate } else if (credential instanceof PasswordCredential) { String username = ((PasswordCredential) credential).getId(); String password = ((PasswordCredential) credential).getPassword(); // Use id and password to send to your server to validate and authenticate } else if (credential instanceof CustomCredential) { if (ExampleCustomCredential.TYPE.equals(credential.getType())) { try { ExampleCustomCredential customCred = ExampleCustomCredential.createFrom(customCredential.getData()); // Extract the required credentials and complete the // authentication as per the federated sign in or any external // sign in library flow } catch (ExampleCustomCredential.ExampleCustomCredentialParsingException e) { // Unlikely to happen. If it does, you likely need to update the // dependency version of your external sign-in library. Log.e(TAG, "Failed to parse an ExampleCustomCredential", e); } } else { // Catch any unrecognized custom credential type here. Log.e(TAG, "Unexpected type of credential"); } } else { // Catch any unrecognized credential type here. Log.e(TAG, "Unexpected type of credential"); } }
Ví dụ sau đây cho thấy cách định dạng yêu cầu JSON khi bạn nhận được một khoá truy cập:
{
"challenge": "T1xCsnxM2DNL2KdK5CLa6fMhD7OBqho6syzInk_n-Uo",
"allowCredentials": [],
"timeout": 1800000,
"userVerification": "required",
"rpId": "credential-manager-app-test.glitch.me"
}
Ví dụ sau đây cho thấy phản hồi JSON trông như thế nào sau khi bạn nhận được thông tin xác thực khoá công khai:
{
"id": "KEDetxZcUfinhVi6Za5nZQ",
"type": "public-key",
"rawId": "KEDetxZcUfinhVi6Za5nZQ",
"response": {
"clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiVDF4Q3NueE0yRE5MMktkSzVDTGE2Zk1oRDdPQnFobzZzeXpJbmtfbi1VbyIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
"authenticatorData": "j5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGQdAAAAAA",
"signature": "MEUCIQCO1Cm4SA2xiG5FdKDHCJorueiS04wCsqHhiRDbbgITYAIgMKMFirgC2SSFmxrh7z9PzUqr0bK1HZ6Zn8vZVhETnyQ",
"userHandle": "2HzoHm_hY0CjuEESY9tY6-3SdjmNHOoNqaPDcZGzsr0"
}
}
Xử lý các trường hợp ngoại lệ khi không có thông tin xác thực
Trong một số trường hợp, có thể người dùng sẽ không có thông tin xác thực hoặc không đồng ý sử dụng một thông tin xác thực hiện có. Nếu getCredential() được gọi và không tìm thấy thông tin xác thực, thì hệ thống sẽ trả về NoCredentialException. Nếu trường hợp này xảy ra, mã của bạn sẽ xử lý các thực thể NoCredentialException.
Kotlin
try {
val credential = credentialManager.getCredential(credentialRequest)
} catch (e: NoCredentialException) {
Log.e("CredentialManager", "No credential available", e)
}
Java
try {
Credential credential = credentialManager.getCredential(credentialRequest);
} catch (NoCredentialException e) {
Log.e("CredentialManager", "No credential available", e);
}
Trên Android 14 trở lên, bạn có thể giảm độ trễ khi hiện bộ chọn tài khoản thông qua phương thức prepareGetCredential() trước khi gọi getCredential().
Kotlin
val response = credentialManager.prepareGetCredential(
GetCredentialRequest(
listOf(
<getPublicKeyCredentialOption>,
<getPasswordOption>
)
)
}
Java
GetCredentialResponse response = credentialManager.prepareGetCredential(
new GetCredentialRequest(
Arrays.asList(
new PublicKeyCredentialOption(),
new PasswordOption()
)
)
);
Phương thức prepareGetCredential() không gọi các phần tử trên giao diện người dùng mà chỉ giúp bạn thực hiện công việc chuẩn bị để sau này có thể chạy thao tác get-credential còn lại (có liên quan đến giao diện người dùng) thông qua API getCredential().
Dữ liệu đã lưu vào bộ nhớ đệm sẽ được trả về trong đối tượng PrepareGetCredentialResponse. Nếu có sẵn thông tin xác thực, kết quả sẽ được lưu vào bộ nhớ đệm để sau này, bạn có thể chạy API getCredential() còn lại nhằm hiển thị bộ chọn tài khoản cùng với dữ liệu đã lưu vào bộ nhớ đệm.
Quy trình đăng ký
Bạn có thể đăng ký phương thức xác thực cho người dùng bằng khoá truy cập hoặc mật khẩu.
Tạo một khoá truy cập
Để giúp người dùng có lựa chọn đăng ký khoá truy cập và dùng khoá truy cập đó cho quá trình xác thực lại, hãy đăng ký thông tin xác thực người dùng bằng cách sử dụng đối tượng CreatePublicKeyCredentialRequest.
Kotlin
fun createPasskey(requestJson: String, preferImmediatelyAvailableCredentials: Boolean) { val createPublicKeyCredentialRequest = CreatePublicKeyCredentialRequest( // Contains the request in JSON format. Uses the standard WebAuthn // web JSON spec. requestJson = requestJson, // Defines whether you prefer to use only immediately available // credentials, not hybrid credentials, to fulfill this request. // This value is false by default. preferImmediatelyAvailableCredentials = preferImmediatelyAvailableCredentials, ) // Execute CreateCredentialRequest asynchronously to register credentials // for a user account. Handle success and failure cases with the result and // exceptions, respectively. coroutineScope.launch { try { val result = credentialManager.createCredential( // Use an activity-based context to avoid undefined system // UI launching behavior context = activityContext, request = createPublicKeyCredentialRequest, ) handlePasskeyRegistrationResult(result) } catch (e : CreateCredentialException){ handleFailure(e) } } } fun handleFailure(e: CreateCredentialException) { when (e) { is CreatePublicKeyCredentialDomException -> { // Handle the passkey DOM errors thrown according to the // WebAuthn spec. handlePasskeyError(e.domError) } is CreateCredentialCancellationException -> { // The user intentionally canceled the operation and chose not // to register the credential. } is CreateCredentialInterruptedException -> { // Retry-able error. Consider retrying the call. } is CreateCredentialProviderConfigurationException -> { // Your app is missing the provider configuration dependency. // Most likely, you're missing the // "credentials-play-services-auth" module. } is CreateCredentialUnknownException -> ... is CreateCredentialCustomException -> { // You have encountered an error from a 3rd-party SDK. If you // make the API call with a request object that's a subclass of // CreateCustomCredentialRequest using a 3rd-party SDK, then you // should check for any custom exception type constants within // that SDK to match with e.type. Otherwise, drop or log the // exception. } else -> Log.w(TAG, "Unexpected exception type ${e::class.java.name}") } }
Java
public void createPasskey(String requestJson, boolean preferImmediatelyAvailableCredentials) { CreatePublicKeyCredentialRequest createPublicKeyCredentialRequest = // `requestJson` contains the request in JSON format. Uses the standard // WebAuthn web JSON spec. // `preferImmediatelyAvailableCredentials` defines whether you prefer // to only use immediately available credentials, not hybrid credentials, // to fulfill this request. This value is false by default. new CreatePublicKeyCredentialRequest( requestJson, preferImmediatelyAvailableCredentials); // Execute CreateCredentialRequest asynchronously to register credentials // for a user account. Handle success and failure cases with the result and // exceptions, respectively. credentialManager.createCredentialAsync( // Use an activity-based context to avoid undefined system // UI launching behavior requireActivity(), createPublicKeyCredentialRequest, cancellationSignal, executor, new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() { @Override public void onResult(CreateCredentialResponse result) { handleSuccessfulCreatePasskeyResult(result); } @Override public void onError(CreateCredentialException e) { if (e instanceof CreatePublicKeyCredentialDomException) { // Handle the passkey DOM errors thrown according to the // WebAuthn spec. handlePasskeyError(((CreatePublicKeyCredentialDomException)e).getDomError()); } else if (e instanceof CreateCredentialCancellationException) { // The user intentionally canceled the operation and chose not // to register the credential. } else if (e instanceof CreateCredentialInterruptedException) { // Retry-able error. Consider retrying the call. } else if (e instanceof CreateCredentialProviderConfigurationException) { // Your app is missing the provider configuration dependency. // Most likely, you're missing the // "credentials-play-services-auth" module. } else if (e instanceof CreateCredentialUnknownException) { } else if (e instanceof CreateCredentialCustomException) { // You have encountered an error from a 3rd-party SDK. If // you make the API call with a request object that's a // subclass of // CreateCustomCredentialRequest using a 3rd-party SDK, // then you should check for any custom exception type // constants within that SDK to match with e.type. // Otherwise, drop or log the exception. } else { Log.w(TAG, "Unexpected exception type " + e.getClass().getName()); } } } ); }
Định dạng yêu cầu JSON
Sau khi tạo một khoá truy cập, bạn phải liên kết khoá truy cập đó với một tài khoản của người dùng và lưu trữ khoá công khai của khoá truy cập trên máy chủ của bạn. Ví dụ về mã sau đây cho thấy cách định dạng yêu cầu JSON khi bạn tạo một khoá truy cập.
Bài đăng này trên blog về xác thực liền mạch trong ứng dụng sẽ hướng dẫn bạn cách định dạng yêu cầu JSON khi tạo mã xác thực và khi xác thực bằng khoá truy cập. Bài đăng này cũng giải thích lý do mật khẩu không phải là giải pháp xác thực hiệu quả, cùng với cách tận dụng thông tin xác thực sinh trắc học có sẵn, cách liên kết ứng dụng với trang web mà bạn sở hữu, cách tạo mã xác thực và cách xác thực bằng cách sử dụng mã xác thực.
{
"challenge": "abc123",
"rp": {
"name": "Credential Manager example",
"id": "credential-manager-test.example.com"
},
"user": {
"id": "def456",
"name": "helloandroid@gmail.com",
"displayName": "helloandroid@gmail.com"
},
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
},
{
"type": "public-key",
"alg": -257
}
],
"timeout": 1800000,
"attestation": "none",
"excludeCredentials": [
{"id": "ghi789", "type": "public-key"},
{"id": "jkl012", "type": "public-key"}
],
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"residentKey": "required",
"userVerification": "required"
}
}
Đặt giá trị cho authenticatorAttachment
Bạn chỉ có thể đặt tham số authenticatorAttachment tại thời điểm tạo thông tin xác thực. Bạn có thể chỉ định platform, cross-platform hoặc không giá trị nào. Trong hầu hết mọi trường hợp, bạn không nên sử dụng giá trị nào.
platform: Để đăng ký thiết bị hiện tại của người dùng hoặc nhắc người dùng sử dụng mật khẩu nâng cấp lên khoá truy cập sau khi đăng nhập, hãy đặtauthenticatorAttachmentthànhplatform.cross-platform: Giá trị này thường dùng khi đăng ký thông tin xác thực đa yếu tố và không được dùng trong ngữ cảnh khoá truy cập.- Không có giá trị: Để cung cấp cho người dùng sự linh hoạt trong việc tạo khoá truy cập trên thiết bị ưu tiên của họ (chẳng hạn như trong phần cài đặt tài khoản), bạn không nên chỉ định tham số
authenticatorAttachmentkhi người dùng chọn thêm khoá truy cập. Trong hầu hết mọi trường hợp, tốt nhất là bạn không nên chỉ định tham số.
Ngăn việc tạo khoá truy cập trùng lặp
Liệt kê mã thông tin xác thực trong mảng excludeCredentials (không bắt buộc) để ngăn việc tạo khoá truy cập mới nếu đã có một khoá truy cập của cùng một nhà cung cấp khoá truy cập.
Xử lý phản hồi JSON
Đoạn mã sau đây minh hoạ phản hồi JSON mẫu để tạo thông tin xác thực khoá công khai. Tìm hiểu thêm về cách xử lý thông tin đăng nhập của khoá công khai trả về.
{
"id": "KEDetxZcUfinhVi6Za5nZQ",
"type": "public-key",
"rawId": "KEDetxZcUfinhVi6Za5nZQ",
"response": {
"clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoibmhrUVhmRTU5SmI5N1Z5eU5Ka3ZEaVh1Y01Fdmx0ZHV2Y3JEbUdyT0RIWSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViUj5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGRdAAAAAAAAAAAAAAAAAAAAAAAAAAAAEChA3rcWXFH4p4VYumWuZ2WlAQIDJiABIVgg4RqZaJyaC24Pf4tT-8ONIZ5_Elddf3dNotGOx81jj3siWCAWXS6Lz70hvC2g8hwoLllOwlsbYatNkO2uYFO-eJID6A"
}
}
Xác minh nguồn gốc dữ liệu JSON của ứng dụng
origin đại diện cho ứng dụng hoặc trang web đưa ra yêu cầu và được khoá truy cập dùng để chống lại các cuộc tấn công giả mạo.
Máy chủ ứng dụng của bạn cần phải kiểm tra nguồn gốc dữ liệu ứng dụng theo một danh sách cho phép gồm các ứng dụng và trang web đã được phê duyệt. Nếu máy chủ nhận được yêu cầu của một ứng dụng hoặc trang web từ một nguồn không xác định, thì yêu cầu đó sẽ bị từ chối.
Trong trường hợp Web, origin cho biết có cùng nguồn gốc với trang web nơi thông tin đăng nhập được nhập. Ví dụ: với URL là https://www.example.com:8443/store?category=shoes#athletic, origin sẽ là https://www.example.com:8443.
Đối với các ứng dụng Android, tác nhân người dùng sẽ tự động đặt origin thành chữ ký của ứng dụng gọi. Chữ ký này phải được xác minh là trùng khớp trên máy chủ của bạn để xác thực phương thức gọi của API khoá truy cập. origin Android là một URI bắt nguồn từ hàm băm SHA-256 của chứng chỉ ký APK, chẳng hạn như:
android:apk-key-hash:<sha256_hash-of-apk-signing-cert>
Bạn có thể tìm thấy hàm băm SHA-256 của chứng chỉ ký này trong một kho khoá bằng cách chạy lệnh sau trong cửa sổ dòng lệnh:
keytool -list -keystore <path-to-apk-signing-keystore>Hàm băm SHA-256 ở định dạng thập lục phân được phân tách bằng dấu hai chấm (91:F7:CB:F9:D6:81…) và các giá trị origin của Android được mã hoá base64url.
Ví dụ dùng đoạn mã Python này minh hoạ cách chuyển đổi định dạng hàm băm sang một định dạng thập lục phân tương thích được phân tách bằng dấu hai chấm:
import binascii
import base64
fingerprint = '91:F7:CB:F9:D6:81:53:1B:C7:A5:8F:B8:33:CC:A1:4D:AB:ED:E5:09:C5'
print("android:apk-key-hash:" + base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))
Hãy thay thế giá trị của fingerprint bằng giá trị của riêng bạn. Dưới đây là một kết quả mẫu:
android:apk-key-hash:kffL-daBUxvHpY-4M8yhTavt5QnFEI2LsexohxrGPYU
Sau đó, bạn có thể so khớp chuỗi đó dưới dạng một nguồn gốc được phép trên máy chủ của bạn. Nếu bạn có nhiều chứng chỉ ký (chẳng hạn như chứng chỉ để gỡ lỗi và phát hành) hoặc nhiều ứng dụng, hãy lặp lại quy trình và chấp nhận mọi nguồn gốc đó đều hợp lệ trên máy chủ.
Lưu mật khẩu của người dùng
Nếu người dùng cung cấp tên người dùng và mật khẩu cho luồng xác thực trong ứng dụng, thì bạn có thể đăng ký thông tin xác thực người dùng để dùng cho mục đích xác thực người dùng. Để thực hiện việc này, hãy tạo đối tượng CreatePasswordRequest:
Kotlin
fun registerPassword(username: String, password: String) { // Initialize a CreatePasswordRequest object. val createPasswordRequest = CreatePasswordRequest(id = username, password = password) // Create credential and handle result. coroutineScope.launch { try { val result = credentialManager.createCredential( // Use an activity based context to avoid undefined // system UI launching behavior. activityContext, createPasswordRequest ) handleRegisterPasswordResult(result) } catch (e: CreateCredentialException) { handleFailure(e) } } }
Java
void registerPassword(String username, String password) { // Initialize a CreatePasswordRequest object. CreatePasswordRequest createPasswordRequest = new CreatePasswordRequest(username, password); // Register the username and password. credentialManager.createCredentialAsync( // Use an activity-based context to avoid undefined // system UI launching behavior requireActivity(), createPasswordRequest, cancellationSignal, executor, new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() { @Override public void onResult(CreateCredentialResponse result) { handleResult(result); } @Override public void onError(CreateCredentialException e) { handleFailure(e); } } ); }
Hỗ trợ khôi phục thông tin đăng nhập
Nếu không còn quyền truy cập vào thiết bị lưu trữ thông tin đăng nhập, thì người dùng có thể khôi phục thông qua bản sao lưu bảo mật trực tuyến. Để tìm hiểu thêm về cách hỗ trợ quá trình khôi phục thông tin xác thực này, hãy đọc phần có tiêu đề "Khôi phục quyền truy cập hoặc thêm thiết bị mới" trong bài đăng này trên blog: Tính bảo mật của khoá truy cập trong Trình quản lý mật khẩu của Google.
Thêm tính năng hỗ trợ các công cụ quản lý mật khẩu bằng URL phổ biến của điểm cuối khoá truy cập
Để tích hợp liền mạch và đảm bảo khả năng tương thích sau này với các công cụ quản lý mật khẩu và thông tin xác thực, bạn nên thêm tính năng hỗ trợ các URL phổ biến của điểm cuối khoá truy cập. Đây là một giao thức mở cho các bên liên kết để chính thức quảng cáo tính năng hỗ trợ khoá truy cập cũng như cung cấp các đường liên kết trực tiếp để đăng ký và quản lý khoá truy cập.
- Đối với một bên phụ thuộc tại
https://example.com, có một trang web cùng với các ứng dụng Android và iOS, URL phổ biến sẽ làhttps://example.com/.well-known/passkey-endpoints. Khi URL được truy vấn, phản hồi phải sử dụng lược đồ sau
{ "enroll": "https://example.com/account/manage/passkeys/create" "manage": "https://example.com/account/manage/passkeys" }Để mở đường liên kết này ngay trong ứng dụng của bạn thay vì trên web, hãy sử dụng đường liên kết trong ứng dụng Android.
Bạn có thể xem thêm thông tin chi tiết trong tài liệu giải thích về URL phổ biến của điểm cuối khoá truy cập trên GitHub.
Giúp người dùng quản lý khoá truy cập bằng cách cho biết nhà cung cấp nào đã tạo khoá truy cập
Một thách thức mà người dùng gặp phải khi quản lý nhiều khoá truy cập liên kết với một ứng dụng nhất định là xác định khoá truy cập chính xác để chỉnh sửa hoặc xoá. Để hỗ trợ giải quyết vấn đề này, bạn nên thêm thông tin bổ sung như nhà cung cấp đã tạo thông tin xác thực, ngày tạo và ngày sử dụng gần đây nhất vào danh sách khoá truy cập trên màn hình cài đặt của ứng dụng.Thông tin về nhà cung cấp được lấy bằng cách kiểm tra AAGUID liên kết với khoá truy cập tương ứng. Bạn có thể tìm thấy AAGUID trong dữ liệu trình xác thực của khoá truy cập.
Ví dụ: nếu người dùng tạo khoá truy cập trên một thiết bị chạy Android bằng Trình quản lý mật khẩu của Google, thì RP sẽ nhận được một AAGUID có dạng như sau: "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4". Bên phụ thuộc có thể chú thích khoá truy cập trong danh sách khoá truy cập để cho biết khoá truy cập đó được tạo bằng Trình quản lý mật khẩu của Google.
Để liên kết AAGUID với nhà cung cấp khoá truy cập, RP có thể sử dụng kho lưu trữ AAGUID do cộng đồng cung cấp. Tìm AAGUID trên danh sách để tìm tên và biểu tượng của nhà cung cấp khoá truy cập.
Đọc thêm về cách tích hợp AAGUID.
Khắc phục các lỗi thường gặp
Hãy tham khảo Hướng dẫn khắc phục sự cố của Trình quản lý thông tin xác thực để biết các mã lỗi, nội dung mô tả và thông tin về nguyên nhân gây ra lỗi thường gặp.
Tài nguyên khác
Để tìm hiểu thêm về Credential Manager API và khoá truy cập, hãy xem các tài nguyên sau:
- Hướng dẫn về trải nghiệm người dùng với khoá truy cập
- Video: Cách giảm sự phụ thuộc vào mật khẩu trong các ứng dụng Android bằng sự hỗ trợ của khoá truy cập
- Lớp học lập trình: Tìm hiểu cách đơn giản hoá quy trình xác thực bằng cách sử dụng Credential Manager API trong ứng dụng Android
- Ứng dụng mẫu: CredentialManager