Triển khai quy trình xác minh email

Hướng dẫn này mô tả cách triển khai tính năng truy xuất email đã xác minh bằng Digital Credentials Verifier API thông qua yêu cầu OpenID for Verifiable Presentations (OpenID4VP).

Thêm phần phụ thuộc

Trong tệp build.gradle của ứng dụng, hãy thêm các phần phụ thuộc sau cho Trình quản lý thông tin xác thực:

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

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

Sử dụng ngữ cảnh của ứng dụng hoặc hoạt động để 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)

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

Để yêu cầu một email xác minh, hãy tạo một GetCredentialRequest chứa GetDigitalCredentialOption. Tuỳ chọn này yêu cầu một chuỗi requestJson được định dạng dưới dạng yêu cầu OpenID cho Bản trình bày có thể xác minh (OpenID4VP).

JSON yêu cầu OpenID4VP phải tuân theo một cấu trúc cụ thể. Các nhà cung cấp hiện tại hỗ trợ cấu trúc JSON có trình bao bọc "digital": {"requests": [...] bên ngoài.

    val nonce = generateSecureRandomNonce()

    // This request follows the OpenID4VP spec
    val openId4vpRequest = """
{
  "requests": [
    {
      "protocol": "openid4vp-v1-unsigned",
      "data": {
        "response_type": "vp_token",
        "response_mode": "dc_api",
        "nonce": "$nonce",
        "dcql_query": {
          "credentials": [
            {
              "id": "user_info_query",
              "format": "dc+sd-jwt",
               "meta": {
                  "vct_values": ["UserInfoCredential"]
               },
              "claims": [
                {"path": ["email"]},
                {"path": ["name"]},  
                {"path": ["given_name"]},
                {"path": ["family_name"]},
                {"path": ["picture"]},
                {"path": ["hd"]},
                {"path": ["email_verified"]}
              ]
            }
          ]
        }
      }
    }
  ]
}
"""

    val getDigitalCredentialOption = GetDigitalCredentialOption(requestJson = openId4vpRequest)
    val request = GetCredentialRequest(listOf(getDigitalCredentialOption))

Yêu cầu này chứa những thông tin chính sau:

  • Truy vấn DCQL: dcql_query chỉ định loại thông tin xác thực và các thông tin xác nhận được yêu cầu (email_verified). Bạn có thể yêu cầu các thông tin xác nhận khác để xác định cấp độ xác minh. Sau đây là một số thông báo xác nhận quyền sở hữu có thể xuất hiện:
    • email_verified: Trong phản hồi, đây là một giá trị Boolean cho biết email đã được xác minh hay chưa.
    • hd (tên miền được lưu trữ): Trong phản hồi, trường này trống.
  • nonce: Một giá trị ngẫu nhiên, duy nhất và được bảo mật bằng mật mã được tạo cho mỗi yêu cầu. Điều này rất quan trọng đối với bảo mật, vì nó ngăn chặn các cuộc tấn công phát lại.
  • UserInfoCredential: Giá trị này ngụ ý một loại thông tin xác thực kỹ thuật số cụ thể chứa các thuộc tính của người dùng. Việc đưa thông tin này vào yêu cầu là rất quan trọng để phân biệt trường hợp sử dụng xác minh email.

Tiếp theo, gói JSON openId4vpRequest trong GetDigitalCredentialOption, tạo GetCredentialRequest và gọi getCredential().

Trình bày yêu cầu cho người dùng

Trình bày yêu cầu cho người dùng bằng giao diện người dùng tích hợp sẵn của Trình quản lý thông tin xác thực.

try {
    // Requesting Digital Credential from user...
    val result = credentialManager.getCredential(activity, request)

    when (val credential = result.credential) {
        is DigitalCredential -> {
            val responseJsonString = credential.credentialJson

            // Successfully received digital credential response.

            // Next, parse this response and send it to your server.
            // ...
        }

        else -> {
            // handle Unexpected State() - Up to the developer
        }
    }
} catch (e: Exception) {
    // handle exceptions - Up to the developer
}

Phân tích cú pháp phản hồi trên ứng dụng

Sau khi nhận được phản hồi, bạn có thể thực hiện phân tích cú pháp sơ bộ trên ứng dụng. Điều này rất hữu ích cho việc cập nhật giao diện người dùng ngay lập tức, chẳng hạn như bằng cách hiển thị tên người dùng.

Mã sau đây trích xuất JWT tiết lộ có chọn lọc (SD-JWT) thô và sử dụng trình trợ giúp để giải mã các thông tin xác nhận quyền sở hữu.

// 1. Parse the outer JSON wrapper to get the `vp_token`
val responseData = JSONObject(responseJsonString)
val vpToken = responseData.getJSONObject("vp_token")

// 2. Extract the raw SD-JWT string
val credentialId = vpToken.keys().next()
val rawSdJwt = vpToken.getJSONArray(credentialId).getString(0)

// 3. Use your parser to get the verified claims
// Server-side validation/parsing is highly recommended.

// Assumes a local parser like the one in our SdJwtParser.kt sample
val claims = SdJwtParser.parse(rawSdJwt)
Log.d("TAG", "Parsed Claims: ${claims.toString(2)}")

// 4. Create your VerifiedUserInfo object with REAL data
val userInfo = VerifiedUserInfo(
    email = claims.getString("email"),
    displayName = claims.optString("name", claims.getString("email"))
)

Xử lý phản hồi

Credential Manager API sẽ trả về phản hồi DigitalCredential.

Sau đây là ví dụ về hình thức của responseJsonString thô và hình thức của các thông báo xác nhận quyền sở hữu sau khi phân tích cú pháp SD-JWT bên trong, nơi bạn nhận được thêm siêu dữ liệu cùng với email đã xác minh:

/*
// Example of the raw JSON response from credential.credentialJson:
{
  "vp_token": {
    // This key matches the 'id' you set in your dcql_query
    "user_info_query": [
      // The SD-JWT string (Issuer JWT ~ Disclosures ~ Key Binding JWT)
      "eyJhbGciOiJ...~WyI...IiwgImVtYWlsIiwgInVzZXJAZXhhbXBsZS5jb20iXQ~...~eyJhbGciOiJ..."
    ]
  }
}

// Example of the parsed and verified claims from the SD-JWT on your server:
{
  "cnf": {
    "jwk": {..}
  },
  "exp": 1775688222,
  "iat": 1775083422,
  "iss": "https://verifiablecredentials-pa.googleapis.com",
  "vct": "UserInfoCredential",
  "email": "jane.doe.246745@gmail.com",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Doe",
  "name": "Jane Doe",
  "picture": "http://example.com/janedoe/me.jpg",
  "hd": ""
}
 */

Xác thực phía máy chủ để tạo tài khoản

Vì email được truy xuất đã được xác minh bằng mật mã, nên bạn có thể bỏ qua bước xác minh OTP qua email, giúp giảm đáng kể trở ngại khi đăng ký và có khả năng tăng lượt chuyển đổi. Quá trình này được xử lý tốt nhất trên máy chủ của bạn. Ứng dụng khách gửi phản hồi thô (chứa vp_token) và số chỉ dùng một lần ban đầu đến một điểm cuối máy chủ mới.

Để xác minh, ứng dụng của bạn phải gửi toàn bộ responseJsonString đến máy chủ của bạn để xác thực bằng mật mã trước khi tạo tài khoản hoặc đăng nhập cho người dùng.

Thông tin xác thực kỹ thuật số cung cấp hai cấp độ xác minh quan trọng cho máy chủ của bạn:

  • Tính xác thực của dữ liệu: Việc xác minh URL của tổ chức phát hành (iss) và chữ ký SD-JWT chứng minh rằng một tổ chức đáng tin cậy đã phát hành dữ liệu này.
  • Danh tính của người trình bày: Việc xác minh trường cnf và chữ ký Liên kết khoá (kb) sẽ xác nhận rằng thông tin xác thực đang được chia sẻ bởi cùng một thiết bị mà thông tin xác thực đó được cấp ban đầu, ngăn chặn việc thông tin xác thực bị chặn hoặc sử dụng trên một thiết bị khác.

Quá trình xác thực trên máy chủ phải đạt được những điều sau:

  • Xác minh công ty phát hành: Đảm bảo trường iss (công ty phát hành) khớp với https://verifiablecredentials-pa.googleapis.com.
  • Xác minh chữ ký: Kiểm tra chữ ký của SD-JWT bằng khoá công khai (JWK) có tại https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks.

Để đảm bảo an toàn tuyệt đối, hãy nhớ xác thực cả nonce để ngăn chặn các cuộc tấn công lặp lại.

Bằng cách kết hợp các bước này, máy chủ của bạn có thể xác thực cả tính xác thực của dữ liệu và danh tính của người trình bày, đảm bảo thông tin xác thực không bị chặn hoặc giả mạo trước khi cấp tài khoản mới.

try {
    // Send the raw credential response and the original nonce to your server.
    // Your server must validate the response. createAccountWithVerifiedCredentials
    // is a custom implementation per each RP for server side verification and account creation.
    val serverResponse = createAccountWithVerifiedCredentials(responseJsonString, nonce)

    // Server returns the new account info (e.g., email, name)
    val claims = JSONObject(serverResponse.json)

    val userInfo = VerifiedUserInfo(
        email = claims.getString("email"),
        displayName = claims.optString("name", claims.getString("email"))
    )

    // handle response - Up to the developer
} catch (e: Exception) {
    // handle exceptions - Up to the developer
}

Tạo khoá truy cập

Sau khi cấp tài khoản, bạn nên tạo ngay một khoá truy cập cho tài khoản đó (không bắt buộc nhưng nên làm). Điều này cung cấp một phương thức đăng nhập an toàn, không cần mật khẩu cho người dùng. Quy trình này giống hệt với quy trình đăng ký khoá truy cập tiêu chuẩn.

Hỗ trợ WebView

Để quy trình này hoạt động trên WebView, nhà phát triển nên triển khai một cầu nối JavaScript (JS Bridge) để hỗ trợ quá trình chuyển giao. Cầu nối này cho phép đối tượng WebView báo hiệu cho ứng dụng gốc, sau đó ứng dụng gốc có thể thực hiện lệnh gọi thực tế đến API Trình quản lý thông tin xác thực.

Xem thêm