ความเข้ากันได้ของเวอร์ชัน

ฟีเจอร์ Restore Credentials ของ Credential Manager ทำงานในอุปกรณ์ที่ใช้ Android 9 (API ระดับ 28) ขึ้นไป, บริการ Google Play (GMS) Core เวอร์ชัน 24220000 ขึ้นไป และไลบรารี androidx.credentials เวอร์ชัน 1.5.0 ขึ้นไป

สิ่งที่ต้องมีก่อน

ตั้งค่าเซิร์ฟเวอร์ Relying Party ให้คล้ายกับเซิร์ฟเวอร์สำหรับ พาสคีย์ หาก คุณตั้งค่า เซิร์ฟเวอร์ เพื่อจัดการการตรวจสอบสิทธิ์ด้วยพาสคีย์ไว้แล้ว ให้ใช้การติดตั้งใช้งานฝั่งเซิร์ฟเวอร์เดียวกันสำหรับคีย์การกู้คืน

ความสัมพันธ์

เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในไฟล์ build.gradle ของโมดูลแอป

Kotlin

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

Groovy

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

ฟีเจอร์ Restore Credentials พร้อมใช้งานในไลบรารี androidx.credentials เวอร์ชัน 1.5.0 ขึ้นไป อย่างไรก็ตาม เราขอแนะนำให้ใช้ทรัพยากร Dependency เวอร์ชันเสถียรล่าสุดหากเป็นไปได้

ภาพรวม

  1. สร้างคีย์การกู้คืน: หากต้องการสร้างคีย์การกู้คืน ให้ทำตาม ขั้นตอนต่อไปนี้:
    1. สร้างอินสแตนซ์ของ Credential Manager: สร้าง CredentialManager ออบเจ็กต์
    2. รับตัวเลือกการสร้างข้อมูลเข้าสู่ระบบจากเซิร์ฟเวอร์แอป: ส่งรายละเอียดที่จำเป็นไปยังแอปไคลเอ็นต์เพื่อสร้างคีย์การกู้คืนจากเซิร์ฟเวอร์แอป
    3. สร้างคีย์การกู้คืน: สร้างคีย์การกู้คืนสำหรับบัญชีของผู้ใช้ หากผู้ใช้ลงชื่อเข้าใช้แอป
    4. **จัดการการตอบกลับการสร้างข้อมูลเข้าสู่ระบบ**: ส่งข้อมูลเข้าสู่ระบบ จากแอปไคลเอ็นต์ไปยังเซิร์ฟเวอร์แอปเพื่อประมวลผล และจัดการ ข้อยกเว้น
  2. ลงชื่อเข้าใช้ด้วยคีย์การกู้คืน: หากต้องการลงชื่อเข้าใช้ด้วยคีย์การกู้คืน ให้ทำตามขั้นตอนต่อไปนี้
    1. รับตัวเลือกการดึงข้อมูลเข้าสู่ระบบจากเซิร์ฟเวอร์แอป: ส่งรายละเอียดที่จำเป็นไปยัง แอปไคลเอ็นต์เพื่อดึงคีย์การกู้คืนจาก เซิร์ฟเวอร์แอป
    2. รับคีย์การกู้คืน: ขอคีย์การกู้คืนจาก Credential Manager เมื่อผู้ใช้ตั้งค่าอุปกรณ์เครื่องใหม่ ซึ่งจะช่วยให้ผู้ใช้ลงชื่อเข้าใช้ได้โดยไม่ต้องป้อนข้อมูลเพิ่มเติม
    3. จัดการการตอบกลับการดึงข้อมูลเข้าสู่ระบบ: ส่งคีย์การกู้คืน จากแอปไคลเอ็นต์ไปยังเซิร์ฟเวอร์แอปเพื่อลงชื่อเข้าใช้ผู้ใช้
  3. ลบคีย์การกู้คืน

สร้างคีย์การกู้คืน

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

  • หากผู้ใช้ลงชื่อเข้าใช้และยังไม่ได้สร้างคีย์การกู้คืน (เช่น ในเมธอด onCreate สำหรับ Activity หลัก)
  • เมื่อผู้ใช้ลงชื่อเข้าใช้หรือทำขั้นตอนการลงทะเบียนบัญชีใหม่ให้เสร็จสมบูรณ์

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

สร้างอินสแตนซ์ของ Credential Manager

ใช้อินสแตนซ์ของ CredentialManager โดยใช้บริบทกิจกรรมของแอป

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

รับตัวเลือกการสร้างข้อมูลเข้าสู่ระบบจากเซิร์ฟเวอร์แอป

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

สร้างคีย์การกู้คืน

หลังจากแยกวิเคราะห์ตัวเลือกการสร้างคีย์สาธารณะที่เซิร์ฟเวอร์ส่งมาแล้ว ให้สร้างคีย์การกู้คืนโดยใส่ตัวเลือกเหล่านี้ในออบเจ็กต์ CreateRestoreCredentialRequest และเรียกใช้เมธอด createCredential() ด้วยออบเจ็กต์ CredentialManager

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

ประเด็นสำคัญเกี่ยวกับโค้ด

  • ออบเจ็กต์ CreateRestoreCredentialRequest มีช่องต่อไปนี้

    • requestJson: ตัวเลือกการสร้างข้อมูลเข้าสู่ระบบที่เซิร์ฟเวอร์แอปส่งมาใน รูปแบบ Web Authentication API สำหรับ PublicKeyCredentialCreationOptionsJSON

    • isCloudBackupEnabled: ช่อง Boolean เพื่อกำหนดว่าจะสำรองข้อมูลคีย์การกู้คืนไปยังระบบคลาวด์หรือไม่ โดยค่าเริ่มต้น แฟล็กนี้จะเป็น true ช่องนี้มีค่าต่อไปนี้

      • true: (แนะนำ) ค่านี้จะเปิดใช้การสำรองข้อมูลคีย์การกู้คืนไปยังระบบคลาวด์หากผู้ใช้เปิดใช้การสำรองข้อมูลของ Google และการเข้ารหัสจากต้นทางถึงปลายทาง เช่น การล็อกหน้าจอ
      • false: ค่านี้จะบันทึกคีย์ในเครื่องและไม่บันทึกลงในระบบคลาวด์ คีย์จะไม่พร้อมใช้งานในอุปกรณ์เครื่องใหม่หากผู้ใช้เลือกที่จะกู้คืนจากระบบคลาวด์

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

Credential Manager API จะแสดงผลการตอบกลับประเภท CreateRestoreCredentialResponse การตอบกลับนี้จะเก็บการตอบกลับการลงทะเบียนข้อมูลเข้าสู่ระบบคีย์สาธารณะ ในรูปแบบ JSON

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

จัดการข้อยกเว้นต่อไปนี้ในระหว่างกระบวนการสร้างคีย์การกู้คืน

  • CreateRestoreCredentialDomException: ข้อยกเว้นนี้เกิดขึ้นหาก requestJson ไม่ถูกต้องและไม่ได้เป็นไปตามรูปแบบ WebAuthn สำหรับ PublicKeyCredentialCreationOptionsJSON
  • E2eeUnavailableException: ข้อยกเว้นนี้เกิดขึ้นหาก isCloudBackupEnabled เป็น true แต่อุปกรณ์ของผู้ใช้ไม่มีการสำรองข้อมูลหรือการเข้ารหัสจากต้นทางถึงปลายทาง เช่น การล็อกหน้าจอ
    หากต้องการให้สร้างข้อมูลเข้าสู่ระบบสำหรับการกู้คืนในทุกกรณี คุณต้องจัดการ E2eeUnavailableException อย่างชัดเจนโดยเรียกใช้ createCredential โดยตั้งค่า isCloudBackupEnabled เป็น true หากระบบแสดง E2eeUnavailableException ให้ดักจับและเรียกใช้ createCredential อีกครั้งโดยตั้งค่า isCloudBackupEnabled เป็น false
  • IllegalArgumentException: ข้อยกเว้นนี้เกิดขึ้นหาก createRestoreRequest ว่างเปล่าหรือไม่ใช่ JSON ที่ถูกต้อง หรือหากไม่มี user.id ที่ เป็นไปตามข้อกำหนดของ WebAuthn specifications

ลงชื่อเข้าใช้ด้วยคีย์การกู้คืน

ใช้ฟีเจอร์ Restore Credentials เพื่อลงชื่อเข้าใช้ผู้ใช้โดยไม่มีการแจ้งเตือนในระหว่างกระบวนการตั้งค่าอุปกรณ์

รับตัวเลือกการดึงข้อมูลเข้าสู่ระบบจากเซิร์ฟเวอร์แอป

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

รับคีย์การกู้คืน

หากต้องการรับคีย์การกู้คืนในอุปกรณ์เครื่องใหม่ ให้เรียกใช้เมธอด getCredential() ในออบเจ็กต์ CredentialManager

เราขอแนะนำให้ดึงคีย์การกู้คืนในสถานการณ์ต่อไปนี้

  • เมื่อเปิดแอปเป็นครั้งแรกในอุปกรณ์ การกู้คืนข้อมูลเข้าสู่ระบบในสถานการณ์นี้จะแยกจากการกู้คืนข้อมูลแอป
  • หากเปิดใช้การสำรองและกู้คืนข้อมูลแอป ให้รับคีย์การกู้คืนทันทีหลังจากกู้คืนข้อมูลแอป ใช้ BackupAgent เพื่อกำหนดค่าการสำรองข้อมูลของแอป และตรวจสอบว่าคุณได้ดำเนินการฟังก์ชัน getCredential ให้เสร็จสมบูรณ์ ภายในการเรียกกลับ onRestoreFinished อย่าใช้onRestore เมธอด เนื่องจากจะเรียกใช้สำหรับการสำรองข้อมูลคีย์-ค่าเท่านั้น ในขณะที่ onRestoreFinished จะเรียกใช้สำหรับการกู้คืนข้อมูลสำรองทุกประเภทอย่างน่าเชื่อถือ วิธีนี้จะช่วยหลีกเลี่ยงความล่าช้าที่อาจเกิดขึ้นเมื่อผู้ใช้เปิดอุปกรณ์เครื่องใหม่เป็นครั้งแรก และช่วยให้ผู้ใช้โต้ตอบกับแอปได้โดยไม่ต้องรอให้ผู้ใช้เปิดแอป เช่น วิธีนี้จะช่วยให้แอปส่งการแจ้งเตือนไปยังผู้ใช้ได้ก่อนที่ผู้ใช้จะเปิดแอปเป็นครั้งแรกในอุปกรณ์เครื่องใหม่ ซึ่งมีความเกี่ยวข้องอย่างยิ่งกับแอปการรับส่งข้อความหรือแอปการสื่อสาร

หากคุณสร้าง BackupAgent ใหม่และก่อนหน้านี้เปิดใช้การสำรองข้อมูลด้วย allowBackup="true" ให้ตั้งค่าบูลีน android:fullBackupOnly="true"ใน ไฟล์ Manifest ของแอป วิธีนี้จะช่วยให้มั่นใจได้ว่าระบบจะยังคงลักษณะการทำงานของการสำรองและกู้คืนข้อมูลของแอปไว้

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

Credential Manager API จะแสดงผลการตอบกลับประเภท GetCredentialResponse ข้อมูลเข้าสู่ระบบที่อยู่ในคำตอบนี้เป็นประเภท RestoreCredential อย่างชัดเจน ซึ่งเก็บคีย์สาธารณะไว้

จัดการการตอบกลับการลงชื่อเข้าใช้

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

ลบคีย์การกู้คืน

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

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

ระบบจะนำคีย์การกู้คืนออกในสถานการณ์ต่อไปนี้เท่านั้น

  • การดำเนินการระดับระบบ: ผู้ใช้ถอนการติดตั้งแอปหรือล้างข้อมูลของแอป
  • การเรียกใช้ระดับแอป: ลบคีย์โดยใช้โปรแกรมโดยเรียกใช้ clearCredentialState() เมื่อจัดการการออกจากระบบของผู้ใช้ใน โค้ดของแอป

เมื่อผู้ใช้ออกจากระบบแอป ให้เรียกใช้เมธอด clearCredentialState() ในออบเจ็กต์ CredentialManager

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)