ใช้การยืนยันอีเมล

คู่มือนี้อธิบายวิธีใช้การดึงข้อมูลอีเมลที่ยืนยันแล้วโดยใช้ Digital Credentials Verifier API ผ่านคำขอ OpenID สำหรับการนำเสนอที่ตรวจสอบได้ (OpenID4VP)

เพิ่มทรัพยากร Dependency

ในไฟล์ build.gradle ของแอป ให้เพิ่มทรัพยากร Dependency ต่อไปนี้สำหรับ Credential Manager

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

เริ่มต้นใช้งาน Credential Manager

ใช้บริบทของแอปหรือกิจกรรมเพื่อสร้างออบเจ็กต์ CredentialManager

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

สร้างคำขอข้อมูลเข้าสู่ระบบดิจิทัล

หากต้องการขออีเมลยืนยัน ให้สร้าง GetCredentialRequest ที่มี GetDigitalCredentialOption ตัวเลือกนี้ต้องใช้สตริง requestJson ที่จัดรูปแบบเป็นคำขอ OpenID for Verifiable Presentations (OpenID4VP)

JSON ของคำขอ OpenID4VP ต้องเป็นไปตามโครงสร้างที่เฉพาะเจาะจง ผู้ให้บริการปัจจุบันรองรับโครงสร้าง JSON ที่มี Wrapper "digital": {"requests": [...]} ด้านนอก

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

คำขอมีข้อมูลสำคัญต่อไปนี้

  • คำค้นหา DCQL: dcql_query ระบุประเภทข้อมูลเข้าสู่ระบบและการอ้างสิทธิ์ที่ขอ (email_verified) คุณสามารถขอการอ้างสิทธิ์อื่นๆ เพื่อกำหนดระดับการยืนยันได้ ตัวอย่างคำกล่าวอ้างที่เป็นไปได้มีดังนี้
    • email_verified: ในการตอบกลับ ค่านี้เป็นบูลีนที่ระบุว่าอีเมลได้รับการยืนยันแล้วหรือไม่
    • hd (โดเมนที่ฝากบริการ): ในการตอบกลับ ช่องนี้จะว่างเปล่า
  • nonce: ระบบจะสร้างค่าสุ่มที่ไม่ซ้ำกันและปลอดภัยด้วยการเข้ารหัสลับสำหรับคำขอแต่ละรายการ ซึ่งสำคัญต่อความปลอดภัยเนื่องจากจะช่วยป้องกันการโจมตีแบบ Replay Attack
  • UserInfoCredential: ค่านี้หมายถึงข้อมูลเข้าสู่ระบบดิจิทัลประเภทหนึ่งๆ ที่มีแอตทริบิวต์ของผู้ใช้ การรวมข้อมูลนี้ไว้ในคำขอเป็นสิ่งสำคัญในการแยกแยะกรณีการใช้งานการยืนยันอีเมล

จากนั้นรวม JSON openId4vpRequest ไว้ใน GetDigitalCredentialOption สร้าง GetCredentialRequest และเรียกใช้ getCredential()

แสดงคำขอต่อผู้ใช้

แสดงคำขอต่อผู้ใช้โดยใช้ UI ในตัวของ Credential Manager

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
}

แยกวิเคราะห์การตอบกลับในไคลเอ็นต์

หลังจากได้รับการตอบกลับแล้ว คุณสามารถทำการแยกวิเคราะห์เบื้องต้นในไคลเอ็นต์ได้ ซึ่งมีประโยชน์ในการอัปเดต UI ทันที เช่น โดยการแสดงชื่อของผู้ใช้

โค้ดต่อไปนี้จะดึงข้อมูล Selective Disclosure JWT (SD-JWT) ดิบและใช้ตัวช่วยเพื่อถอดรหัสการอ้างสิทธิ์

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

จัดการการตอบกลับ

Credential Manager API จะแสดงผลการตอบกลับ DigitalCredential

ต่อไปนี้คือตัวอย่างลักษณะของ responseJsonString ดิบ และลักษณะของการอ้างสิทธิ์หลังจากแยกวิเคราะห์ SD-JWT ภายในซึ่งคุณจะได้รับข้อมูลเมตาเพิ่มเติมพร้อมกับอีเมลที่ยืนยันแล้ว

/*
// 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": ""
}
 */

การตรวจสอบฝั่งเซิร์ฟเวอร์สำหรับการสร้างบัญชี

เนื่องจากอีเมลที่ดึงมาได้รับการยืนยันด้วยการเข้ารหัส คุณจึงข้ามขั้นตอนการยืนยัน OTP ทางอีเมลได้ ซึ่งจะช่วยลดความยุ่งยากในการลงชื่อสมัครใช้และอาจเพิ่ม Conversion ได้ กระบวนการนี้ควรได้รับการจัดการบนเซิร์ฟเวอร์ของคุณ ไคลเอ็นต์จะส่งการตอบกลับดิบ (ที่มี vp_token) และ Nonce เดิมไปยังปลายทางเซิร์ฟเวอร์ใหม่

สำหรับการยืนยัน แอปพลิเคชันของคุณต้องส่ง responseJsonString แบบเต็มไปยังเซิร์ฟเวอร์เพื่อตรวจสอบความถูกต้องของการเข้ารหัสก่อนสร้างบัญชีหรือลงชื่อเข้าสู่ระบบของผู้ใช้

ข้อมูลเข้าสู่ระบบดิจิทัลจะให้การยืนยัน 2 ระดับที่สำคัญสำหรับเซิร์ฟเวอร์ของคุณ ดังนี้

  • ความถูกต้องของข้อมูล: การยืนยัน URL ของผู้ออก (iss) และลายเซ็น SD-JWT จะพิสูจน์ได้ว่าหน่วยงานที่เชื่อถือได้เป็นผู้ออกข้อมูลนี้
  • ข้อมูลประจำตัวของผู้นำเสนอ: การยืนยันช่อง cnf และลายเซ็นการเชื่อมโยงคีย์ (kb) จะยืนยันว่ามีการแชร์ข้อมูลเข้าสู่ระบบโดยอุปกรณ์เดียวกับที่ออกข้อมูลเข้าสู่ระบบให้ในตอนแรก ซึ่งจะช่วยป้องกันไม่ให้มีการดักจับหรือใช้ข้อมูลเข้าสู่ระบบในอุปกรณ์อื่น

การตรวจสอบความถูกต้องในเซิร์ฟเวอร์ต้องเป็นไปตามเงื่อนไขต่อไปนี้

  • ยืนยันผู้ออก: ตรวจสอบว่าช่อง iss (ผู้ออก) ตรงกับ https://verifiablecredentials-pa.googleapis.com
  • ยืนยันลายเซ็น: ตรวจสอบลายเซ็นของ SD-JWT โดยใช้คีย์สาธารณะ (JWK) ที่มีให้ที่ https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks

เพื่อความปลอดภัยอย่างเต็มรูปแบบ โปรดตรวจสอบว่าคุณได้ตรวจสอบ nonce เพื่อป้องกันการโจมตีแบบ Replay ด้วย

เมื่อรวมขั้นตอนเหล่านี้เข้าด้วยกัน เซิร์ฟเวอร์จะตรวจสอบได้ทั้งความถูกต้องของข้อมูลและตัวตนของผู้นำเสนอ เพื่อให้มั่นใจว่าข้อมูลเข้าสู่ระบบไม่ได้ถูกดักจับหรือปลอมแปลงก่อนที่จะจัดสรรบัญชีใหม่

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
}

การสร้างพาสคีย์

ขั้นตอนถัดไปที่ไม่บังคับแต่แนะนำอย่างยิ่งหลังจากจัดสรรบัญชีคือการสร้างพาสคีย์สำหรับบัญชีนั้นทันที ซึ่งเป็นวิธีที่ปลอดภัยและไม่ต้องใช้รหัสผ่านในการลงชื่อเข้าใช้ของผู้ใช้ ขั้นตอนการลงทะเบียนนี้เหมือนกับการลงทะเบียนพาสคีย์มาตรฐาน

การรองรับ WebView

เพื่อให้ขั้นตอนทำงานใน WebView ได้ นักพัฒนาแอปควรใช้ JavaScript Bridge (JS Bridge) เพื่ออำนวยความสะดวกในการส่งต่อ บริดจ์นี้ช่วยให้วัตถุ WebView ส่งสัญญาณไปยังแอปที่มาพร้อมเครื่อง ซึ่งจะทำการเรียกใช้ Credential Manager API จริงได้

ดูเพิ่มเติม