Chấp nhận giấy tờ tuỳ thân từ Google Wallet

Trực tuyến

Bạn có thể chấp nhận giấy tờ tuỳ thân điện tử trong cả quy trình trong ứng dụng và trên web. Để chấp nhận thông tin xác thực từ Google Wallet, bạn cần:

1. Tích hợp bằng ứng dụng hoặc web theo hướng dẫn được cung cấp và
2. Điền thông tin vào biểu mẫu này để yêu cầu và đồng ý với điều khoản dịch vụ về việc chấp nhận thông tin xác thực từ Google Wallet.

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

Để kiểm thử việc hiển thị giấy tờ tuỳ thân, trước tiên, bạn phải đăng ký tham gia chương trình beta công khai bằng tài khoản thử nghiệm dự kiến. Sau đó, hãy cung cấp thông tin chi tiết tiếp theo cho người liên hệ được chỉ định của Google.

• Đường liên kết đến Điều khoản dịch vụ
• Biểu trưng
• Trang web
• Mã gói trên Cửa hàng Play (dành cho các hoạt động tích hợp ứng dụng Android)
• Mã nhận dạng Gmail dùng để tham gia chương trình thử nghiệm beta công khai

Định dạng thông tin xác thực được hỗ trợ

Hiện có một số tiêu chuẩn đề xuất xác định định dạng dữ liệu của giấy tờ tuỳ thân kỹ thuật số, trong đó có hai tiêu chuẩn đang thu hút sự quan tâm đáng kể của ngành:

1. mdocs – do ISO xác định.
2. Thông tin xác thực có thể xác minh của W3C – do W3C xác định.

Mặc dù Trình quản lý thông tin xác thực của Android hỗ trợ cả hai định dạng, nhưng Google Wallet hiện chỉ hỗ trợ Thẻ căn cước điện tử dựa trên mdoc.

Trải nghiệm người dùng

Khi một ứng dụng yêu cầu các thuộc tính danh tính, quy trình sau sẽ diễn ra:

1. Khám phá thông tin xác thực: Ứng dụng truy vấn các ví có sẵn để xác định thông tin xác thực có thể đáp ứng yêu cầu. Sau đó, Android sẽ hiển thị một bộ chọn giao diện người dùng hệ thống, cho thấy thông tin cần chia sẻ. Điều này cho phép người dùng đưa ra quyết định sáng suốt về thông tin xác thực cần sử dụng.

2. Lựa chọn của người dùng và tương tác với ví: Người dùng chọn một thông tin xác thực và Android sẽ gọi ứng dụng ví tương ứng để hoàn tất giao dịch. Ứng dụng ví có thể hiển thị màn hình yêu cầu đồng ý riêng hoặc yêu cầu xác nhận bằng sinh trắc học.

Kết quả: Nếu người dùng đồng ý, thông tin xác thực danh tính đã chọn sẽ được chia sẻ với ứng dụng yêu cầu. Nếu người dùng từ chối, hệ thống sẽ trả về một lỗi.

Trong ứng dụng

Để yêu cầu thông tin xác thực danh tính từ ứng dụng Android, hãy làm theo các bước sau:

Cập nhật phần phụ thuộc

Trong build.gradle của dự án, hãy cập nhật các phần phụ thuộc để sử dụng Trình quản lý thông tin xác thực (thử nghiệm):

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")
}

Đị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:

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

Yêu cầu thuộc tính nhận dạng

Thay vì chỉ định từng tham số riêng lẻ cho các yêu cầu danh tính, ứng dụng sẽ cung cấp tất cả các tham số đó dưới dạng một chuỗi JSON trong CredentialOption. Trình quản lý thông tin xác thực sẽ chuyển chuỗi JSON này đến các ví điện tử có sẵn mà không cần kiểm tra nội dung của chuỗi. Sau đó, mỗi ví sẽ chịu trách nhiệm: – Phân tích cú pháp chuỗi JSON để hiểu yêu cầu về danh tính. – Xác định thông tin xác thực nào (nếu có) được lưu trữ đáp ứng yêu cầu.

Dự kiến W3C sẽ chính thức xác định cấu trúc của yêu cầu JSON này trong thông số kỹ thuật API web. Tuy nhiên, điều quan trọng là bạn phải nhớ rằng thông số kỹ thuật này đang ở dạng dự thảo và có thể thay đổi.

Ban đầu, chúng tôi sẽ sử dụng giao thức xem trước để lấy giấy tờ tuỳ thân từ Google Wallet. Điều này cho phép chúng ta bắt đầu tích hợp và kiểm thử trong khi hoàn tất thông số kỹ thuật API web.

Dưới đây là mẫu requestJson mdoc cho giao thức xem trước:

{
  identity: {
    providers: [{
      holder: {
        selector: {
          format: ['mdoc'],
          type: 'org.iso.18013.5.1.mDL',
          fields: [
            'org.iso.18013.5.1.family_name',
            'org.iso.18013.5.1.portrait',
          ]
        },
        params: {
          nonce: '1234',
          readerPublicKey: '<public_key>',
          extraParamAsNeededByWallets: true,
        },
      },
    }]
  }
}

// The request in the JSON format to conform with
// the JSON-ified Digital Credentials 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)
)

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}")
    }
}

Phản hồi sẽ trả về một identityToken (chuỗi JSON) do W3C xác định. Ứng dụng Wallet chịu trách nhiệm tạo phản hồi này.

Ví dụ:

{
    "token": "<base64 encoded response>"
}

Gửi mã thông báo và xử lý trên máy chủ

Sau khi nhận được identityToken, ứng dụng của bạn sẽ truyền mã này đến máy chủ ứng dụng để xác minh. Bước đầu tiên là giải mã mã thông báo từ định dạng base64. Mảng byte thu được đại diện cho dữ liệu CBOR, tuân thủ CDDL sau.

CredentialDocument = {
  "version": tstr,       // Set to "ANDROID-HPKE-v1"
  "pkEm": bstr,          // Public key, in uncompressed form
  "cipherText": bstr     // The encrypted data
}

Bước tiếp theo là tính toán SessionTranscript từ tiêu chuẩn ISO/IEC 18013-5:2021 với cấu trúc Chuyển đổi dành riêng cho Android:

SessionTranscript = [
  null,                // DeviceEngagementBytes not available
  null,                // EReaderKeyBytes not available
  AndroidHandover      // Defined below
]

AndroidHandover = [
  "AndroidHandoverv1", // Version number
  nonce,               // nonce that comes from request
  appId,               // RP package name
  pkRHash,             // The SHA256 hash of the recipient public key
]

cipherText được mã hoá bằng phương thức mã hoá HPKE. Để giải mã, hãy sử dụng SessionTranscript làm Dữ liệu đã xác thực bổ sung, cùng với khoá riêng tư EC đã tạo trước đó và các chế độ cài đặt sau:

• KEM: DHKEM(P-256, HKDF-SHA256)
• KDF: HKDF-SHA256
• AEAD: AES-128-GCM

Văn bản thô thu được là các byte CBOR DeviceResponse như được xác định trong tiêu chuẩn ISO/IEC 18013-5:2021. DeviceResponse phải được xác thực theo điều khoản 9 của tiêu chuẩn ISO/IEC 18013-5:2021. Quá trình này bao gồm một số bước, chẳng hạn như xác minh rằng mdoc bắt nguồn từ một tổ chức phát hành đáng tin cậy và phản hồi được ký bởi thiết bị dự định. Bạn có thể sử dụng lớp DeviceResponseParser từ dự án Thông tin xác thực danh tính của OpenWallet Foundation trong một phần của quy trình xác thực này.

Web

Để yêu cầu Thông tin xác thực danh tính bằng API Thông tin xác thực kỹ thuật số trên Chrome, bạn cần đăng ký bản dùng thử theo nguyên gốc của API Thông tin xác thực kỹ thuật số.

Giao lưu trực tiếp

Để chấp nhận giấy tờ tuỳ thân qua Google Wallet, bạn cần thực hiện các bước sau:

• Tạo hoặc mua đầu đọc để chấp nhận giấy tờ tuỳ thân theo định nghĩa của ISO 18013-5
• Tải chứng chỉ IACA vào đầu đọc để đảm bảo giấy tờ tuỳ thân được chấp nhận là chính xác
• Kiểm thử giải pháp
• Đăng ký ứng dụng của bạn với Google Wallet

Tạo hoặc mua đầu đọc để chấp nhận giấy tờ tuỳ thân theo định nghĩa của ISO 18013-5

Giấy tờ tuỳ thân trong Wallet được triển khai theo tiêu chuẩn ISO 18013-5 đối với giấy phép lái xe trên thiết bị di động. Các công nghệ này sử dụng cơ chế tương tác dựa trên NFC hoặc mã QR cùng với BLE làm cơ chế truyền dữ liệu. Vì vậy, mọi thiết bị có thể triển khai các khía cạnh đó của tiêu chuẩn đều có thể đóng vai trò là trình đọc, ngay cả ứng dụng di động. Vì tiêu chuẩn này là mở, nên có một số cách triển khai của bên thứ ba trên thị trường. Ngoài ra, bạn có thể triển khai chức năng này trực tiếp nếu cần.

Để biết hướng dẫn về cách tự triển khai chức năng này, hãy xem ứng dụng Android của trình đọc tài liệu tham khảo nguồn mở. Ứng dụng này triển khai tiêu chuẩn ISO và có thể chấp nhận mDL từ Google Wallet.

Bạn có thể bắt đầu bằng cách tạo và chạy ứng dụng trình đọc tài liệu tham khảo:

• Sao chép kho lưu trữ ứng dụng tham chiếu
• Mở dự án trên Android Studio
• Tạo và chạy mục tiêu appverifier trên thiết bị Android hoặc trình mô phỏng.

Tải chứng chỉ IACA vào đầu đọc để đảm bảo giấy tờ tuỳ thân được chấp nhận là chính xác

Để xác thực thông tin xác thực thực, bạn phải có giấy tờ tuỳ thân trong ví của một tổ chức phát hành được hỗ trợ. Dưới đây là danh sách các tổ chức phát hành được Google Wallet hỗ trợ cùng với đường liên kết đến chứng chỉ của họ để xác minh.

• Arizona
• California
• Colorado
• Gruzia
• Maryland

Kiểm thử giải pháp

Để kiểm thử giải pháp của bạn, hãy tạo và chạy ứng dụng Android của chúng tôi có phần giữ tham chiếu nguồn mở. Sau đây là các bước để tạo và chạy ứng dụng trình giữ tham chiếu:

• Sao chép kho lưu trữ ứng dụng tham chiếu
• Mở dự án trên Android Studio
• Tạo và chạy mục tiêu appholder trên thiết bị Android hoặc trình mô phỏng.

(Không bắt buộc) Đăng ký ứng dụng của bạn với Google Wallet

Đăng ký ứng dụng của bạn với Google Wallet bằng cách điền vào biểu mẫu này.