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

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

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

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

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

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

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

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

Kotlin

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

Groovy

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

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

ภาพรวม

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

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

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

สร้างอินสแตนซ์ของ 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 แต่อุปกรณ์ของผู้ใช้ไม่มีการสำรองข้อมูลหรือการเข้ารหัสจากต้นทางถึงปลายทาง เช่น การล็อกหน้าจอ
  • IllegalArgumentException: ข้อยกเว้นนี้จะเกิดขึ้นหาก createRestoreRequest ว่างเปล่าหรือไม่ใช่ JSON ที่ถูกต้อง หรือหากไม่มี user.id ที่ เป็นไปตามข้อกำหนดของ WebAuthn specifications

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

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

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

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

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

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

คุณสามารถดึงคีย์การกู้คืนได้ในสถานการณ์ต่อไปนี้

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

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

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

Credential Manager API จะแสดงผลการตอบกลับประเภท GetCredentialResponse การตอบกลับนี้จะเก็บคีย์สาธารณะ

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

ส่งคีย์สาธารณะจากแอปไปยังเซิร์ฟเวอร์ 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)