הטמעה של שחזור פרטי כניסה באמצעות Credential Manager

בדף הזה מוסבר איך ליצור מפתח שחזור, להיכנס איתו ולמחוק אותו.

תאימות גרסאות

התכונה 'שחזור פרטי הכניסה' של Credential Manager פועלת במכשירים עם Android מגרסה 9 ואילך, עם Google Play Services (GMS) Core מגרסה 24220000 ואילך, ועם גרסה 1.5.0 ואילך של ספריית androidx.credentials.

דרישות מוקדמות

מגדירים שרת של צד שלישי בדומה לשרת של מפתחות גישה. אם כבר הגדרתם שרת לטיפול באימות באמצעות מפתחות גישה, אתם יכולים להשתמש באותו יישום בצד השרת כדי לשחזר מפתחות.

תלויות

מוסיפים את יחסי התלות הבאים לקובץ build.gradle של מודול האפליקציה:

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

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

התכונה Restore Credentials זמינה מגרסה 1.5.0 ומעלה של ספריית androidx.credentials. עם זאת, מומלץ להשתמש בגרסאות היציבות העדכניות ביותר של התלות, ככל האפשר.

סקירה כללית

1. יצירת מפתח שחזור: כדי ליצור מפתח שחזור, מבצעים את השלבים הבאים:
   1. הפעלת Credential Manager: יצירת אובייקט CredentialManager
   2. קבלת אפשרויות ליצירת פרטי כניסה משרת האפליקציה: שליחת הפרטים שנדרשים ליצירת מפתח השחזור משרת האפליקציה לאפליקציית הלקוח.
   3. יצירת מפתח שחזור: יוצרים מפתח שחזור לחשבון של המשתמש אם הוא מחובר לאפליקציה.
   4. טיפול בתגובה ליצירת פרטי הכניסה: שולחים את פרטי הכניסה מאפליקציית הלקוח לשרת האפליקציה לצורך עיבוד, ומטפלים בחריגים.
2. כניסה באמצעות מפתח שחזור: כדי להיכנס באמצעות מפתח שחזור, פועלים לפי השלבים הבאים:
   1. קבלת אפשרויות לאחזור פרטי הכניסה משרת האפליקציה: שליחת הפרטים שנדרשים לאחזור מפתח השחזור משרת האפליקציה לאפליקציית הלקוח.
   2. קבלת מפתח השחזור: בקשה של מפתח השחזור ממנהל האישורים כשמשתמש מגדיר מכשיר חדש. כך המשתמש יכול להיכנס לחשבון בלי להזין פרטים נוספים.
   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.

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: הערך הזה שומר את המפתח באופן מקומי ולא בענן. המפתח לא יהיה זמין במכשיר החדש אם המשתמש יבחר לשחזר מהענן.

טיפול בתגובה ליצירת פרטי הכניסה

ה-Credential Manager API מחזיר תגובה מהסוג CreateRestoreCredentialResponse. התגובה הזו מכילה את התגובה לרישום של פרטי הכניסה של המפתח הציבורי בפורמט JSON.

שולחים את המפתח הציבורי מהאפליקציה לשרת של הצד המסתמך. המפתח הציבורי הזה דומה למפתח הציבורי שנוצר כשיוצרים מפתח גישה. אותו קוד שמטפל ביצירת מפתח גישה בשרת יכול גם לטפל ביצירת מפתח שחזור. מידע נוסף על הטמעה בצד השרת זמין במדריך בנושא מפתחות גישה.

במהלך תהליך יצירת מפתח השחזור, צריך לטפל בחריגים הבאים:

• ‫CreateRestoreCredentialDomException: החריגה הזו מתרחשת אם הערך של ‫requestJson לא תקין ולא תואם לפורמט WebAuthn של ‫PublicKeyCredentialCreationOptionsJSON.
• ‫E2eeUnavailableException: החריג הזה מתרחש אם isCloudBackupEnabled הוא true, אבל במכשיר של המשתמש אין גיבוי נתונים או הצפנה מקצה לקצה, כמו נעילת מסך.
• ‫IllegalArgumentException: החריגה הזו מתרחשת אם createRestoreRequest ריק או לא בפורמט JSON תקין, או אם אין לו user.id תקין שתואם למפרטים של WebAuthn.

כניסה באמצעות מפתח שחזור

שימוש ב'שחזור פרטי כניסה' כדי שהמשתמש ייכנס לחשבון באופן שקט במהלך תהליך הגדרת המכשיר.

קבלת אפשרויות לאחזור פרטי כניסה משרת האפליקציות

שולחים לאפליקציית הלקוח את האפשרויות הנדרשות כדי לקבל את מפתח השחזור מהשרת. הוראות דומות לשימוש במפתח גישה בשלב הזה מפורטות במאמר כניסה באמצעות מפתח גישה. מידע נוסף על ההטמעה בצד השרת זמין במדריך לאימות בצד השרת.

קבלת מפתח השחזור

כדי לקבל את מפתח השחזור במכשיר החדש, קוראים לשיטה getCredential() באובייקט CredentialManager.

אפשר לאחזר את מפתח השחזור בתרחישים הבאים:

• (מומלץ) מיד אחרי שנתוני האפליקציה משוחזרים. משתמשים ב-BackupAgent כדי להגדיר את הגיבוי של האפליקציה ולהשלים את הפונקציונליות של getCredential בתוך הקריאה החוזרת (callback) של onRestore כדי לוודא שהאישורים של האפליקציה ישוחזרו מיד אחרי שנתוני האפליקציה ישוחזרו. כך נמנעים עיכובים פוטנציאליים כשמשתמשים פותחים את המכשיר החדש שלהם בפעם הראשונה, והם יכולים ליצור אינטראקציה בלי לחכות שהאפליקציה שלכם תיפתח.
• בפעם הראשונה שמפעילים את האפליקציה במכשיר.

כדי לשלוח למשתמש התראות לפני שהוא פותח את האפליקציה בפעם הראשונה במכשיר חדש, צריך לאחזר את מפתח השחזור בתוך הקריאה החוזרת (callback) של 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. התשובה הזו מכילה את המפתח הציבורי.

טיפול בתגובת הכניסה

שולחים את המפתח הציבורי מהאפליקציה לשרת של הצד המסתמך, שאפשר להשתמש בו כדי שהמשתמש ייכנס לחשבון. בצד השרת, הפעולה הזו דומה לכניסה באמצעות מפתח גישה. אותו קוד שמטפל בכניסה באמצעות מפתחות גישה בשרת יכול לטפל גם בכניסות באמצעות מפתחות שחזור. מידע נוסף על הטמעה של מפתחות גישה בצד השרת זמין במאמר כניסה באמצעות מפתח גישה.

מחיקת מפתח השחזור

מנהל האישורים הוא חסר מצב (stateless) ולא מודע לפעילות המשתמש, ולכן הוא לא מוחק אוטומטית את מפתחות השחזור אחרי השימוש בהם. כדי למחוק מפתח שחזור, צריך להפעיל את method‏ clearCredentialState(). מטעמי אבטחה, צריך למחוק את המפתח בכל פעם שמשתמש יוצא מהחשבון. כך תוכלו לוודא שבפעם הבאה שהמשתמש יפתח את האפליקציה באותו מכשיר, הוא ינותק מהחשבון ויוצג לו מסך שיבקש ממנו להיכנס שוב.

הסרת ההתקנה של אפליקציה מתפרשת ככוונה למחוק את מפתח השחזור התואם מהמכשיר, בדומה לכוונה של המשתמש כשהוא מתנתק מהחשבון.

מפתחות שחזור מוסרים רק במצבים הבאים:

• פעולות ברמת המערכת: משתמשים מסירים את האפליקציה או מוחקים את הנתונים שלה.
• קריאות ברמת האפליקציה: מוחקים את המפתח באופן פרוגרמטי על ידי קריאה ל-clearCredentialState() כשמטפלים בהתנתקות של משתמש בקוד של האפליקציה.

כשהמשתמש מתנתק מהאפליקציה, צריך להפעיל את ה-method‏ 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)