Triển khai tính năng Khôi phục thông tin xác thực bằng Trình quản lý thông tin xác thực

Trang này mô tả cách tạo, đăng nhập bằng và xoá khoá khôi phục.

Khả năng tương thích giữa các phiên bản

Tính năng Khôi phục thông tin đăng nhập của Trình quản lý thông tin đăng nhập hoạt động trên các thiết bị chạy Android 9 trở lên, GMS Core phiên bản 24220000 trở lên và phiên bản 1.5.0 trở lên của thư viện androidx.credentials.

Điều kiện tiên quyết

Thiết lập một máy chủ bên thứ ba đáng tin cậy tương tự như máy chủ cho khoá truy cập. Nếu bạn đã thiết lập một máy chủ để xử lý việc xác thực bằng khoá truy cập, hãy sử dụng cùng một quy trình triển khai phía máy chủ cho khoá khôi phục.

Phần phụ thuộc

Thêm các phần phụ thuộc sau vào tệp build.gradle của mô-đun ứng dụng:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

Tính năng Khôi phục thông tin xác thực có trong thư viện androidx.credentials phiên bản 1.5.0 trở lên. Tuy nhiên, bạn nên sử dụng các phiên bản ổn định mới nhất của các phần phụ thuộc nếu có thể.

Tổng quan

  1. Tạo khoá khôi phục: Để tạo khoá khôi phục, hãy hoàn tất các bước sau:
    1. Khởi tạo Trình quản lý thông tin xác thực: Tạo một đối tượng CredentialManager.
    2. Nhận các lựa chọn tạo thông tin đăng nhập từ máy chủ ứng dụng: Gửi cho ứng dụng khách thông tin chi tiết cần thiết để tạo khoá khôi phục từ máy chủ ứng dụng của bạn.
    3. Tạo khoá khôi phục: Tạo khoá khôi phục cho tài khoản của người dùng nếu người dùng đã đăng nhập vào ứng dụng của bạn.
    4. Xử lý phản hồi tạo thông tin xác thực: Gửi thông tin xác thực từ ứng dụng khách đến máy chủ ứng dụng để xử lý và xử lý mọi trường hợp ngoại lệ.
  2. Đăng nhập bằng khoá khôi phục: Để đăng nhập bằng khoá khôi phục, hãy hoàn tất các bước sau:
    1. Nhận các lựa chọn truy xuất thông tin đăng nhập từ máy chủ ứng dụng: Gửi cho ứng dụng khách các thông tin chi tiết cần thiết để truy xuất khoá khôi phục từ máy chủ ứng dụng của bạn.
    2. Lấy khoá khôi phục: Yêu cầu khoá khôi phục từ Trình quản lý thông tin xác thực khi người dùng thiết lập một thiết bị mới. Nhờ đó, người dùng có thể đăng nhập mà không cần nhập thêm thông tin.
    3. Xử lý phản hồi truy xuất thông tin xác thực: Gửi khoá khôi phục từ ứng dụng khách đến máy chủ ứng dụng để đăng nhập người dùng.
  3. Xoá khoá khôi phục.

Tạo khoá khôi phục

Tạo khoá khôi phục sau khi người dùng xác thực với ứng dụng của bạn – ngay sau khi đăng nhập hoặc trong lần khởi chạy ứng dụng tiếp theo nếu họ đã đăng nhập.

Khởi tạo Trình quản lý thông tin xác thực

Sử dụng ngữ cảnh hoạt động của ứng dụng để tạo một đối tượng CredentialManager.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Nhận các lựa chọn tạo thông tin đăng nhập từ máy chủ ứng dụng

Sử dụng một thư viện tuân thủ FIDO trong máy chủ ứng dụng để gửi cho ứng dụng khách của bạn thông tin cần thiết để tạo thông tin đăng nhập khôi phục, chẳng hạn như thông tin về người dùng, ứng dụng và các thuộc tính cấu hình bổ sung. Để biết thêm thông tin về việc triển khai phía máy chủ, hãy xem Hướng dẫn phía máy chủ.

Tạo khoá khôi phục

Sau khi phân tích cú pháp các lựa chọn tạo khoá công khai do máy chủ gửi, hãy tạo khoá khôi phục bằng cách bao bọc các lựa chọn này trong một đối tượng CreateRestoreCredentialRequest và gọi phương thức createCredential() bằng đối tượng CredentialManager.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

Các điểm chính về mã

  • Đối tượng CreateRestoreCredentialRequest chứa các trường sau:

    • requestJson: Các lựa chọn tạo thông tin đăng nhập do máy chủ ứng dụng gửi ở định dạng Web Authentication API cho PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: Trường Boolean để xác định xem có nên sao lưu khoá khôi phục lên đám mây hay không. Theo mặc định, cờ này là true. Trường này có các giá trị sau:

      • true: (Nên dùng) Giá trị này cho phép sao lưu các khoá khôi phục lên đám mây nếu người dùng đã bật tính năng Sao lưu của Google và tính năng mã hoá đầu cuối, chẳng hạn như khoá màn hình.
      • false: Giá trị này lưu khoá cục bộ chứ không lưu trên đám mây. Khoá không có trên thiết bị mới nếu người dùng chọn khôi phục từ đám mây.

Xử lý phản hồi tạo thông tin xác thực

API Trình quản lý thông tin xác thực trả về một phản hồi thuộc loại CreateRestoreCredentialResponse. Phản hồi này chứa phản hồi đăng ký thông tin xác thực khoá công khai ở định dạng JSON.

Gửi khoá công khai từ ứng dụng của bạn đến máy chủ bên thứ ba đáng tin cậy. Khoá công khai này tương tự như khoá công khai được tạo khi bạn tạo khoá truy cập. Cùng một đoạn mã xử lý việc tạo khoá truy cập trên máy chủ cũng có thể xử lý việc tạo khoá khôi phục. Để biết thêm thông tin về việc triển khai phía máy chủ, hãy xem hướng dẫn về khoá truy cập.

Trong quá trình tạo khoá khôi phục, hãy xử lý các trường hợp ngoại lệ sau:

  • CreateRestoreCredentialDomException: Ngoại lệ này xảy ra nếu requestJson không hợp lệ và không tuân theo định dạng WebAuthn cho PublicKeyCredentialCreationOptionsJSON.
  • E2eeUnavailableException: Trường hợp ngoại lệ này xảy ra nếu isCloudBackupEnabled là true, nhưng thiết bị của người dùng không có tính năng sao lưu dữ liệu hoặc mã hoá hai đầu, chẳng hạn như khoá màn hình.
  • IllegalArgumentException: Ngoại lệ này xảy ra nếu createRestoreRequest trống hoặc không phải là JSON hợp lệ, hoặc nếu không có user.id hợp lệ tuân thủ quy cách WebAuthn.

Đăng nhập bằng khoá khôi phục

Sử dụng Restore Credentials (Khôi phục thông tin đăng nhập) để đăng nhập người dùng một cách âm thầm trong quá trình thiết lập thiết bị.

Nhận các lựa chọn truy xuất thông tin đăng nhập từ máy chủ ứng dụng

Gửi cho ứng dụng các lựa chọn cần thiết để lấy khoá khôi phục từ máy chủ. Để xem hướng dẫn tương tự về khoá truy cập cho bước này, hãy xem bài viết Đăng nhập bằng khoá truy cập. Để biết thêm thông tin về việc triển khai phía máy chủ, hãy xem hướng dẫn xác thực phía máy chủ.

Lấy khoá khôi phục

Để lấy khoá khôi phục trên thiết bị mới, hãy gọi phương thức getCredential() trên đối tượng CredentialManager.

Bạn có thể tìm nạp khoá khôi phục trong các trường hợp sau:

  • (Nên dùng) Ngay sau khi dữ liệu ứng dụng được khôi phục. Sử dụng BackupAgent để định cấu hình hoạt động sao lưu của ứng dụng và hoàn tất chức năng getCredential trong lệnh gọi lại onRestore để đảm bảo thông tin đăng nhập của ứng dụng được khôi phục ngay sau khi dữ liệu ứng dụng được khôi phục. Điều này giúp tránh được tình trạng chậm trễ có thể xảy ra khi người dùng mở thiết bị mới lần đầu tiên và cho phép người dùng tương tác mà không cần chờ họ mở ứng dụng của bạn.
  • Khi ứng dụng chạy lần đầu tiên trên thiết bị.

Để gửi thông báo cho người dùng trước khi họ mở ứng dụng lần đầu tiên trên một thiết bị mới, hãy tìm nạp khoá khôi phục trong lệnh gọi lại onRestore của BackupAgent. Điều này đặc biệt phù hợp với các ứng dụng nhắn tin hoặc liên lạc.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

Các API trình quản lý thông tin xác thực trả về một phản hồi thuộc loại GetCredentialResponse. Phản hồi này chứa khoá công khai.

Xử lý phản hồi đăng nhập

Gửi khoá công khai từ ứng dụng đến máy chủ của bên phụ thuộc. Sau đó, khoá này có thể được dùng để đăng nhập người dùng. Về phía máy chủ, thao tác này tương tự như thao tác đăng nhập bằng khoá truy cập. Cùng một đoạn mã xử lý việc đăng nhập bằng khoá truy cập trên máy chủ cũng có thể xử lý việc đăng nhập bằng khoá khôi phục. Để biết thêm thông tin về việc triển khai phía máy chủ cho khoá truy cập, hãy xem bài viết Đăng nhập bằng khoá truy cập.

Xoá khoá khôi phục

Credential Manager không có trạng thái và không nhận biết được hoạt động của người dùng, vì vậy, công cụ này không tự động xoá các khoá khôi phục sau khi sử dụng. Để xoá khoá khôi phục, hãy gọi phương thức clearCredentialState(). Để đảm bảo an toàn, hãy xoá khoá mỗi khi người dùng đăng xuất. Điều này đảm bảo rằng vào lần tiếp theo khi người dùng mở ứng dụng trên cùng một thiết bị, người dùng sẽ bị đăng xuất và được nhắc đăng nhập lại.

Việc gỡ cài đặt ứng dụng được hiểu là người dùng có ý định xoá khoá khôi phục tương ứng khỏi thiết bị đó, tương tự như ý định của người dùng khi đăng xuất.

Khoá khôi phục chỉ bị xoá trong các trường hợp sau:

  • Hành động ở cấp hệ thống: Người dùng gỡ cài đặt ứng dụng hoặc xoá dữ liệu của ứng dụng.
  • Lệnh gọi cấp ứng dụng: Xoá khoá theo phương thức lập trình bằng cách gọi clearCredentialState() khi xử lý thao tác đăng xuất của người dùng trong mã của ứng dụng.

Khi người dùng đăng xuất khỏi ứng dụng, hãy gọi phương thức clearCredentialState() trên đối tượng CredentialManager.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)