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 với phiên bản

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

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

Thiết lập một máy chủ bên tin cậy tương tự như máy chủ dành cho khoá truy cập. Nếu bạn đã thiết lập một máy chủ để xử lý quy trình xác thực bằng khoá truy cập, hãy sử dụng cùng một cách 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.7.0-alpha01")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha01"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha01"
}

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 CredentialManager đối tượng.
    2. Nhận các lựa chọn tạo thông tin xác thực từ máy chủ ứng dụng: Gửi cho ứng dụng phía máy khách các thông tin chi tiết cần thiết để tạo khoá khôi phục từ máy chủ ứng dụng.
    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 phía máy 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 xác thực từ máy chủ ứng dụng**: Gửi cho ứng dụng phía máy 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.
    2. Nhận 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. Điều này cho phép người dùng đă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 phía máy 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 để khởi tạo đố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 xác thực từ máy chủ ứng dụng

Sử dụng thư viện tuân thủ FIDO trong máy chủ ứng dụng để gửi cho ứng dụng phía máy khách thông tin cần thiết để tạo thông tin xác thực 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ề cách 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 gói các lựa chọn này trong đối tượng CreateRestoreCredentialRequest và gọi phương thức createCredential() bằng đối tượng CredentialManager.

// createRestoreRequest contains the details sent by the server 
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 xác thực do máy chủ ứng dụng gửi ở định dạng Web Authentication API (API Xác thực web) 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 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á hai đầu, 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á này 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ề 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 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 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ề cách 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: Trường hợp 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 tính năng mã hoá hai đầu, chẳng hạn như khoá màn hình.
  • IllegalArgumentException: Trường hợp 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 trường này không có user.id hợp lệ tuân thủ các thông số kỹ thuật của WebAuthn .

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

Sử dụng tính năng Khôi phục thông tin xác thực để đă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 xác thực từ máy chủ ứng dụng

Gửi cho ứng dụng phía máy khách các lựa chọn cần thiết để nhận khoá khôi phục từ máy chủ. Để biết 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ề cách triển khai phía máy chủ, hãy xem hướng dẫn xác thực phía máy chủ.

Nhận khoá khôi phục

Để nhận 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 tính nă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 xác thực 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ễ tiềm ẩn 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.
  • Trong lần đầu tiên khởi chạy ứng dụng 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 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 giao tiếp.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

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

val response = credentialManager.getCredential(context, getRequest)

Các API trình quản lý thông tin xác thực trả về 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ủ bên tin cậy. Sau đó, bạn có thể dùng khoá này để đăng nhập người dùng. Ở 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 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ề cách 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

Trình quản lý thông tin xác thực không lưu giữ trạng thái và không biết về hoạt động của người dùng, vì vậy, trình quản lý này không tự động xoá 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 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à ý đị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ý việc người dùng đăng xuất trong mã của ứng dụng.

Khi người dùng đăng xuất khỏi ứng dụng của bạn, 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)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)