Credential Manager - Holder API

เครื่องมือจัดการข้อมูลเข้าสู่ระบบ - Holder API ช่วยให้แอป Android จัดการและแสดงข้อมูลเข้าสู่ระบบดิจิทัลต่อผู้ตรวจสอบได้

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

หากต้องการใช้ Credential Manager - Holder API ให้เพิ่มข้อมูลต่อไปนี้ลงในสคริปต์บิลด์ของโมดูลแอป

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

ลงทะเบียนข้อมูลเข้าสู่ระบบด้วย Credential Manager

กระเป๋าสตางค์ต้องลงทะเบียนข้อมูลเมตาของข้อมูลเข้าสู่ระบบเพื่อให้เครื่องมือจัดการข้อมูลเข้าสู่ระบบกรองและแสดงข้อมูลดังกล่าวในเครื่องมือเลือกข้อมูลเข้าสู่ระบบเมื่อมีคำขอเข้ามา

รูปภาพแสดง UI ของข้อมูลเข้าสู่ระบบแบบดิจิทัลในเครื่องมือจัดการข้อมูลเข้าสู่ระบบ
รูปที่ 1 UI ของข้อมูลเข้าสู่ระบบดิจิทัล

UI ตัวเลือกเครื่องมือจัดการข้อมูลเข้าสู่ระบบ

ระบบจะส่งรูปแบบข้อมูลเมตานี้ไปยัง RegisterCredentialsRequest สร้าง [RegistryManager][1] และลงทะเบียนข้อมูลเข้าสู่ระบบ

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

รีจิสทรีจะยังคงอยู่เมื่อรีบูตอุปกรณ์ การจดทะเบียนรีจิสทรีเดียวกันที่มีรหัสและประเภทเดียวกันอีกครั้งจะเขียนทับระเบียนรีจิสทรีก่อนหน้า คุณจึงควรลงทะเบียนอีกครั้งเมื่อข้อมูลเข้าสู่ระบบมีการเปลี่ยนแปลงเท่านั้น

ไม่บังคับ: สร้างเงื่อนไขการจับคู่

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

Credential Manager API จะมีตัวจับคู่สำหรับโปรโตคอลยอดนิยมในปัจจุบัน ซึ่งก็คือ OpenID4VP ยังไม่ได้เผยแพร่อย่างเป็นทางการ ดังนั้นตอนนี้ให้ใช้ sample matcher สำหรับโปรโตคอล OpenID4VP v24

จัดการข้อมูลเข้าสู่ระบบที่เลือก

ถัดไป กระเป๋าสตางค์ต้องจัดการเมื่อผู้ใช้เลือกข้อมูลเข้าสู่ระบบ คุณสามารถกําหนดกิจกรรมที่รอรับandroidx.credentials.registry.provider.action.GET_CREDENTIALตัวกรอง Intent ตัวอย่างกระเป๋าสตางค์ของเราสาธิตขั้นตอนนี้

Intent ที่เปิดใช้งานกิจกรรมจะมีคําขอผู้ตรวจสอบและต้นทางการเรียก ซึ่งสามารถดึงข้อมูลด้วย PendingIntentHandler.retrieveProviderGetCredentialRequest ฟังก์ชัน API จะแสดงผล ProviderGetCredentialRequest ที่มีข้อมูลทั้งหมดที่เกี่ยวข้องกับคำขอผู้ตรวจสอบที่ระบุ องค์ประกอบหลักๆ มี 3 อย่างดังนี้

  • แอปที่ส่งคำขอ คุณดูข้อมูลนี้ได้ด้วย getCallingAppInfo
  • ข้อมูลเข้าสู่ระบบที่เลือก คุณสามารถดูข้อมูลเกี่ยวกับผู้สมัครที่ผู้ใช้เลือกผ่านselectedEntryId Extension Method ซึ่งจะจับคู่กับรหัสข้อมูลเข้าสู่ระบบที่คุณลงทะเบียนไว้
  • คำขอที่เฉพาะเจาะจงที่ผู้ยืนยันส่งมา คุณดูข้อมูลนี้ได้จากเมธอด getCredentialOptions ในกรณีนี้ คุณควรเห็น GetDigitalCredentialOption ในรายการนี้ ซึ่งมีคำขอเอกสารรับรองดิจิทัล

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

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

คุณดูตัวอย่างได้ในกระเป๋าสตางค์ตัวอย่าง

แสดงผล UI ของ Wallet

เมื่อเลือกข้อมูลเข้าสู่ระบบแล้ว ระบบจะเรียกใช้กระเป๋าสตางค์และนําผู้ใช้ไปยัง UI ของกระเป๋าสตางค์ ในตัวอย่างนี้ พรอมต์ข้อมูลไบโอเมตริก

ส่งคำตอบเกี่ยวกับข้อมูลเข้าสู่ระบบ

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

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

หากมีข้อยกเว้น คุณสามารถส่งข้อยกเว้นเกี่ยวกับข้อมูลเข้าสู่ระบบในลักษณะเดียวกัน ดังนี้

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

ดูตัวอย่างวิธีแสดงการตอบกลับข้อมูลเข้าสู่ระบบในบริบทได้จากตัวอย่างแอป