Trình quản lý thông tin xác thực – API trình xác thực

Bạn có thể dùng quy trình xác minh thông tin đăng nhập kỹ thuật số trong các ứng dụng Android để xác thực và cấp quyền cho danh tính của người dùng (chẳng hạn như giấy tờ tuỳ thân do chính phủ cấp), các thuộc tính về người dùng đó (chẳng hạn như giấy phép lái xe, bằng cấp hoặc các thuộc tính như tuổi hoặc địa chỉ) hoặc các trường hợp khác mà thông tin đăng nhập cần được cấp và xác minh để khẳng định tính xác thực của một thực thể.

Thông tin chứng nhận kỹ thuật số là một tiêu chuẩn công khai của W3C, quy định cách truy cập vào thông tin chứng nhận kỹ thuật số có thể xác minh của người dùng từ một ví kỹ thuật số và được triển khai cho các trường hợp sử dụng trên web bằng API Quản lý thông tin chứng nhận của W3C. Trên Android, API DigitalCredential của Trình quản lý thông tin xác thực được dùng để xác minh thông tin xác thực kỹ thuật số.

Triển khai

Để xác minh thông tin đăng nhập kỹ thuật số trong dự án Android, hãy làm như sau:

  1. Thêm các phần phụ thuộc vào tập lệnh bản dựng của ứng dụng và khởi động một lớp CredentialManager.
  2. Tạo một yêu cầu về thông tin xác thực kỹ thuật số và dùng yêu cầu đó để khởi chạy một DigitalCredentialOption, sau đó tạo GetCredentialRequest.
  3. Khởi chạy quy trình getCredential bằng yêu cầu đã tạo để nhận GetCredentialResponse thành công hoặc xử lý mọi trường hợp ngoại lệ có thể xảy ra. Sau khi truy xuất thành công, hãy xác thực phản hồi.

Thêm phần phụ thuộc và khởi chạy

Thêm các phần phụ thuộc sau vào tập lệnh bản dựng Gradle:

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

Tiếp theo, hãy khởi chạy một phiên bản của lớp CredentialManager.

val credentialManager = CredentialManager.create(context)

Tạo một yêu cầu về thông tin xác thực kỹ thuật số

Tạo một yêu cầu về thông tin chứng nhận kỹ thuật số và dùng yêu cầu đó để khởi chạy một DigitalCredentialOption.

// The request in the JSON format to conform with
// the JSON-ified Credential Manager - Verifier API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
    GetDigitalCredentialOption(requestJson = requestJson)

// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
    listOf(digitalCredentialOption)
)

Sau đây là ví dụ về một yêu cầu OpenId4Vp. Bạn có thể xem toàn bộ thông tin tham khảo tại trang web này.

{
  "requests": [
    {
      "protocol": "openid4vp-v1-unsigned",
      "data": {
        "response_type": "vp_token",
        "response_mode": "dc_api",
        "nonce": "OD8eP8BYfr0zyhgq4QCVEGN3m7C1Ht_No9H5fG5KJFk",
        "dcql_query": {
          "credentials": [
            {
              "id": "cred1",
              "format": "mso_mdoc",
              "meta": {
                "doctype_value": "org.iso.18013.5.1.mDL"
              },
              "claims": [
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "family_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "given_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "age_over_21"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Lấy thông tin đăng nhập

Khởi chạy quy trình getCredential bằng yêu cầu đã tạo. Bạn sẽ nhận được GetCredentialResponse thành công hoặc GetCredentialException nếu yêu cầu không thành công.

Quy trình getCredential sẽ kích hoạt hộp thoại hệ thống Android để trình bày các lựa chọn thông tin đăng nhập hiện có của người dùng và thu thập lựa chọn của họ. Tiếp theo, ứng dụng ví chứa lựa chọn thông tin xác thực đã chọn sẽ hiển thị giao diện người dùng để thu thập sự đồng ý và thực hiện các hành động cần thiết để tạo phản hồi thông tin xác thực kỹ thuật số.

coroutineScope.launch {
    try {
        val result = credentialManager.getCredential(
            context = activityContext,
            request = getCredRequest
        )
        verifyResult(result)
    } catch (e : GetCredentialException) {
        handleFailure(e)
    }
}

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential ${credential.type}")
        }
    }
}

// Handle failure.
fun handleFailure(e: GetCredentialException) {
  when (e) {
        is GetCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to share the credential.
        }
        is GetCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is NoCredentialException -> {
            // No credential was available.
        }
        is CreateCredentialUnknownException -> {
            // An unknown, usually unexpected, error has occurred. Check the
            // message error for any additional debugging information.
        }
        is CreateCredentialCustomException -> {
            // You have encountered a custom error thrown by the wallet.
            // If you made 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}")
    }
}