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

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

android skills add restore-credentials

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

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

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

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

פניות קשורות

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

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

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

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

סקירה כללית

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 וקוראים ל-method‏ 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.

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

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

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

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

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

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

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

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

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

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

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

אם אתם יוצרים BackupAgent חדש וכבר הפעלתם גיבוי באמצעות allowBackup="true", הגדירו את הערך הבוליאני android:fullBackupOnly="true" במניפסט של האפליקציה. כך אפשר לוודא שהאפליקציה תמשיך לגבות ולשחזר נתונים כמו שצריך.

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

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

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

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

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