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

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

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

ฟีเจอร์การกู้คืนข้อมูลเข้าสู่ระบบของ 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"
}

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

ภาพรวม

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

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

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

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

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

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

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

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

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

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

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

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

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

เครื่องมือจัดการข้อมูลเข้าสู่ระบบไม่มีสถานะและไม่ทราบกิจกรรมของผู้ใช้ จึงไม่ ลบคีย์การกู้คืนโดยอัตโนมัติหลังจากใช้งาน หากต้องการลบคีย์การกู้คืน ให้เรียกใช้เมธอด 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)