ใช้ข้อมูลเข้าสู่ระบบการกู้คืนด้วยเครื่องมือจัดการข้อมูลเข้าสู่ระบบ

หน้านี้อธิบายวิธีสร้าง ลงชื่อเข้าใช้ และลบคีย์การกู้คืน

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

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

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

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

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

เพิ่มทรัพยากร 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 พร้อมใช้งานตั้งแต่เวอร์ชัน 1.5.0 ขึ้นไปของไลบรารี androidx.credentials อย่างไรก็ตาม เราขอแนะนำให้ใช้ทรัพยากร 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 Backup และการเข้ารหัสจากต้นทางถึงปลายทาง เช่น การล็อกหน้าจอ
      • false: ค่านี้จะบันทึกคีย์ไว้ในเครื่อง ไม่ใช่ในระบบคลาวด์ คีย์จะไม่พร้อมใช้งานในอุปกรณ์ใหม่หากผู้ใช้เลือกกู้คืนจากระบบคลาวด์

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

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

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

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

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

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

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

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

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

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

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

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

  • เมื่อเปิดแอปในอุปกรณ์เป็นครั้งแรก การกู้คืนข้อมูลเข้าสู่ระบบในสถานการณ์นี้ไม่เกี่ยวข้องกับการกู้คืนข้อมูลแอป
  • หากเปิดใช้การสำรองและกู้คืนข้อมูลแอป ให้รับคีย์การกู้คืนทันทีหลังจากกู้คืนข้อมูลแอปแล้ว ใช้ BackupAgent เพื่อกำหนดค่าการสำรองข้อมูลของแอปและตรวจสอบว่าคุณได้ใช้ฟังก์ชัน getCredential ภายใน Callback 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

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

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

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

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

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)