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

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

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

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

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

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

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

การขึ้นต่อกัน

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

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

ภาพรวม

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

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

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

ออบเจ็กต์ CreateRestoreCredentialRequest มีช่องต่อไปนี้
- requestJson: ตัวเลือกการสร้างข้อมูลเข้าสู่ระบบที่เซิร์ฟเวอร์แอปส่งมาในรูปแบบ Web Authentication API สำหรับ PublicKeyCredentialCreationOptionsJSON
- isCloudBackupEnabled: ฟิลด์ Boolean เพื่อพิจารณาว่าควรสำรองข้อมูลคีย์การกู้คืนไปยังระบบคลาวด์หรือไม่ โดยค่าเริ่มต้น แฟล็กนี้จะเป็น true ฟิลด์นี้มีค่าดังนี้
  - true: (แนะนำ) ค่านี้จะเปิดใช้การสำรองข้อมูล คีย์การกู้คืนไปยังระบบคลาวด์หากผู้ใช้มีการสำรองข้อมูลของ Google และ การเข้ารหัสจากต้นทางถึงปลายทาง เช่น การล็อกหน้าจอ ที่เปิดใช้อยู่
  - false: ค่านี้จะบันทึกคีย์ไว้ในเครื่อง ไม่ใช่ในระบบคลาวด์ คีย์จะไม่พร้อมใช้งานในอุปกรณ์เครื่องใหม่หากผู้ใช้เลือก ที่จะกู้คืนจากระบบคลาวด์
ข้อควรระวัง: ขอแนะนำให้ตั้งค่า isCloudBackupEnabled เป็น true หากปิดใช้ข้อมูลสำรองในระบบคลาวด์และผู้ใช้กู้คืนจากข้อมูลสำรองในระบบคลาวด์ การเรียกเพื่อดึงคีย์การกู้คืนจะล้มเหลว ผู้ใช้ที่กู้คืนแอปด้วยข้อมูลสำรองในระบบคลาวด์จะไม่ได้รับคีย์การกู้คืนและระบบจะไม่ลงชื่อเข้าใช้โดยอัตโนมัติ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

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

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

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

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

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

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

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

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

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

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

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)