דף זה תורגם על ידי Cloud Translation API.

כניסה למשתמש באמצעות מנהל האישורים

‫Credential Manager הוא Jetpack API שתומך בכמה שיטות כניסה, כמו שם משתמש וסיסמה, מפתחות גישה ופתרונות כניסה מאוחדים (כמו כניסה באמצעות חשבון Google) ב-API אחד, וכך מפשט את השילוב למפתחים.

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

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

מידע על מפתחות גישה

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

מפתחות הגישה מבוססים על WebAuthn (אימות אינטרנט), תקן שפותח במשותף על ידי FIDO Alliance ו-World Wide Web Consortium (W3C). פרוטוקול WebAuthn משתמש בקריפטוגרפיה של מפתח ציבורי כדי לאמת את המשתמש. האתר או האפליקציה שהמשתמש נכנס אליהם יכולים לראות את המפתח הציבורי ולשמור אותו, אבל אף פעם לא את המפתח הפרטי. המפתח הפרטי נשמר בסוד ובאופן בטוח. בנוסף, מפתחות הגישה הם ייחודיים ומקושרים לאתר או לאפליקציה, ולכן אי אפשר לגנוב אותם באמצעות פישינג, מה שמשפר את האבטחה.

הכלי לניהול פרטי כניסה מאפשר למשתמשים ליצור מפתחות גישה ולאחסן אותם במנהל הסיסמאות של Google.

במאמר אימות משתמש באמצעות מפתחות גישה מוסבר איך להטמיע תהליכי אימות חלקים באמצעות מפתחות גישה עם Credential Manager.

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

כדי להשתמש בכלי לניהול אישורים, צריך לבצע את השלבים שבקטע הזה.

שימוש בגרסה עדכנית של הפלטפורמה

מנהל פרטי הכניסה נתמך ב-Android 4.4 (רמת API‏ 19) ומעלה.

הוספת יחסי תלות לאפליקציה

מוסיפים את יחסי התלות הבאים לסקריפט הבנייה של מודול האפליקציה:

implementation(libs.androidx.credentials)

// optional - needed for credentials support from play services, for devices running
// Android 13 and below.
implementation(libs.androidx.credentials.play.services.auth)build.gradle.kts

מידע נוסף על צמצום, הסתרה ואופטימיזציה של האפליקציה

הוספת תמיכה ב-Digital Asset Links

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

יוצרים קובץ JSON של Digital Asset Links. לדוגמה, כדי להצהיר שלאתר https://signin.example.com ולאפליקציית Android עם שם החבילה com.example יש אפשרות לשתף פרטי כניסה, יוצרים קובץ בשם assetlinks.json עם התוכן הבא:

[
  {
    "relation" : [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target" : {
      "namespace" : "android_app",
      "package_name" : "com.example.android",
      "sha256_cert_fingerprints" : [
        SHA_HEX_VALUE
      ]
    }
  }
]assetlinks.json

השדה relation הוא מערך של מחרוזת אחת או יותר שמתארות את הקשר שמוצהר עליו. כדי להצהיר שאפליקציות ואתרים חולקים פרטי כניסה, מציינים את קשרי הגומלין כ-delegate_permission/handle_all_urls ו-delegate_permission/common.get_login_creds.

השדה target הוא אובייקט שמציין את הנכס שההצהרה חלה עליו. השדות הבאים מזהים אתר:

namespace web

site

כתובת ה-URL של האתר בפורמט https://domain[:optional_port]; לדוגמה, https://www.example.com.

הערך של domain צריך להיות מוגדר במלואו, וצריך להשמיט את optional_port כשמשתמשים ביציאה 443 עבור HTTPS.

יעד site יכול להיות רק דומיין בסיס: אי אפשר להגביל שיוך של אפליקציה לספריית משנה ספציפית. אל תכללו נתיב בכתובת ה-URL, כמו קו נטוי בסוף.

תת-דומיינים לא נחשבים כתואמים: כלומר, אם מציינים את domain כ-www.example.com, הדומיין www.counter.example.com לא משויך לאפליקציה.

השדות הבאים מזהים אפליקציה ל-Android:

`namespace`	`android_app`
`package_name`	שם החבילה שמוצהר במניפסט של האפליקציה. לדוגמה, `com.example.android`
`sha256_cert_fingerprints`	טביעות האצבע בפורמט SHA256 של אישור החתימה של האפליקציה.

מאחסנים את קובץ ה-JSON של Digital Asset Links במיקום הבא בדומיין הכניסה:
```
https://domain[:optional_port]/.well-known/assetlinks.json
```
לדוגמה, אם הדומיין שלכם לכניסה הוא signin.example.com, מארחים את קובץ ה-JSON בכתובת https://signin.example.com/.well-known/assetlinks.json.

סוג ה-MIME של קובץ Digital Asset Links חייב להיות JSON. מוודאים שהשרת שולח כותרת Content-Type: application/json בתגובה.
מוודאים שהמארח מאפשר ל-Google לאחזר את קובץ Digital Asset Link. אם יש לכם קובץ robots.txt, הוא צריך לאפשר לסוכן Googlebot לאחזר /.well-known/assetlinks.json. ברוב האתרים אפשר לאפשר לכל סוכן אוטומטי לאחזר קבצים בנתיב /.well-known/, כדי ששירותים אחרים יוכלו לגשת למטא-נתונים בקבצים האלה:
```
User-agent: *
Allow: /.well-known/
```

מוסיפים את השורה הבאה לקובץ המניפסט בקטע <application>:

<meta-data android:name="asset_statements" android:resource="@string/asset_statements" />

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

מצהירים על השיוך באפליקציה ל-Android. מוסיפים אובייקט שמציין את assetlinks.jsonהקבצים לטעינה. צריך להשתמש בתו בריחה (escape) לכל גרש ולכל מירכאות שמשתמשים בהם במחרוזת. לדוגמה:
```
<string name="asset_statements" translatable="false">
[{
  \"include\": \"https://signin.example.com/.well-known/assetlinks.json\"
}]
</string>
```
הערה: הקישור https://signin.example.com/.well-known/assetlinks.json צריך להחזיר תגובת HTTP 200 עם כותרת JSON MIME Content-Type. החזרה של הפניה מחדש מסוג HTTP 301 או 302 או של סוג תוכן שאינו JSON גורמת לאימות להיכשל. בדוגמה הבאה מוצגת בקשה וכותרות התגובה שקשורות אליה.
```
> GET /.well-known/assetlinks.json HTTP/1.1
> User-Agent: curl/7.35.0
> Host: signin.example.com

< HTTP/1.1 200 OK
< Content-Type: application/json
```

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

כדי להגדיר ולאתחל אובייקט CredentialManager, מוסיפים לוגיקה דומה ללוגיקה הבאה:

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)PasskeyAndPasswordFunctions.kt

ציון שדות להזנת פרטי הכניסה

ב-Android 14 ואילך, אפשר להשתמש במאפיין isCredential כדי לציין שדות של פרטי כניסה, כמו שדות של שם משתמש או סיסמה. המאפיין הזה מציין שהתצוגה הזו היא שדה פרטי כניסה שמיועד לעבוד עם מנהל פרטי הכניסה ועם ספקי פרטי כניסה של צד שלישי, וגם לעזור לשירותי המילוי האוטומטי לספק הצעות טובות יותר למילוי אוטומטי. כשהאפליקציה משתמשת ב-Credential Manager API, מוצג גיליון מידע תחתון של Credential Manager עם פרטי הכניסה הזמינים, ואין צורך להציג עוד את תיבת הדו-שיח של המילוי האוטומטי עבור שם המשתמש או הסיסמה. באופן דומה, אין צורך להציג את תיבת הדו-שיח של השמירה של מילוי אוטומטי לסיסמאות, כי האפליקציה תבקש מ-Credential Manager API לשמור את פרטי הכניסה.

כדי להשתמש במאפיין isCredential, מוסיפים אותו לתצוגות הרלוונטיות:

<TextView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:isCredential="true" />xmlsnippets.xml

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

מאתחלים את אפשרויות האימות באמצעות סיסמה ומפתח גישה:

// Retrieves the user's saved password for your app from their
// password provider.
val getPasswordOption = GetPasswordOption()

// Get passkey from the user's public key credential provider.
val getPublicKeyCredentialOption = GetPublicKeyCredentialOption(
  requestJson = requestJson
)PasskeyAndPasswordFunctions.kt

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

הערה: אפליקציות לא אמורות להגדיר את השדה origin, למעט דפדפנים ואפליקציות עם הרשאות דומות. מידע נוסף
```
val credentialRequest = GetCredentialRequest(
  listOf(getPasswordOption, getPublicKeyCredentialOption),
)PasskeyAndPasswordFunctions.kt
      
```

מפעילים את תהליך הכניסה:

coroutineScope {
  try {
    result = credentialManager.getCredential(
      // Use an activity-based context to avoid undefined system UI
      // launching behavior.
      context = activityContext,
      request = credentialRequest
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    // Handle failure
  }
}PasskeyAndPasswordFunctions.kt

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is PublicKeyCredential -> {
      val responseJson = credential.authenticationResponseJson
      // Share responseJson i.e. a GetCredentialResponse on your server to
      // validate and  authenticate
    }

    is PasswordCredential -> {
      val username = credential.id
      val password = credential.password
      // Use id and password to send to your server to validate
      // and authenticate
    }

    is CustomCredential -> {
      // If you are also using any external sign-in libraries, parse them
      // here with the utility functions provided.
      if (credential.type == ExampleCustomCredential.TYPE) {
        try {
          val ExampleCustomCredential =
            ExampleCustomCredential.createFrom(credential.data)
          // Extract the required credentials and complete the authentication as per
          // the federated sign in or any external sign in library flow
        } catch (e: ExampleCustomCredential.ExampleCustomCredentialParsingException) {
          // Unlikely to happen. If it does, you likely need to update the dependency
          // version of your external sign-in library.
          Log.e(TAG, "Failed to parse an ExampleCustomCredential", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }
    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}PasskeyAndPasswordFunctions.kt

הערה: אם הקריאה ל-Credential Manager הופעלה על ידי פעולת משתמש מפורשת, צריך להגדיר את preferImmediatelyAvailableCredentials ל-false. אם Credential Manager נקרא באופן אופורטוניסטי, צריך להגדיר את הערך של preferImmediatelyAvailableCredentials ל-true.

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

אם מגדירים את preferImmediatelyAvailableCredentials ל-true ואין נתוני כניסה זמינים באופן מיידי, כלי ניהול נתוני הכניסה לא יציג ממשק משתמש והבקשה תיכשל באופן מיידי, ותוחזר NoCredentialException לבקשות get ו-CreateCredentialNoCreateOptionException לבקשות create. מומלץ להשתמש באפשרות הזו כשמפעילים את Credential Manager API באופן אופורטוניסטי, למשל כשפותחים את האפליקציה בפעם הראשונה.

בדוגמה הבאה אפשר לראות איך לעצב את בקשת ה-JSON כשמקבלים מפתח גישה:

{
  "challenge": "T1xCsnxM2DNL2KdK5CLa6fMhD7OBqho6syzInk_n-Uo",
  "allowCredentials": [],
  "timeout": 1800000,
  "userVerification": "required",
  "rpId": "https://passkeys-codelab.glitch.me/"
}

בדוגמה הבאה אפשר לראות איך תגובת JSON יכולה להיראות אחרי שמקבלים אישור מפתח ציבורי:

{
  "id": "KEDetxZcUfinhVi6Za5nZQ",
  "type": "public-key",
  "rawId": "KEDetxZcUfinhVi6Za5nZQ",
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiVDF4Q3NueE0yRE5MMktkSzVDTGE2Zk1oRDdPQnFobzZzeXpJbmtfbi1VbyIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
    "authenticatorData": "j5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGQdAAAAAA",
    "signature": "MEUCIQCO1Cm4SA2xiG5FdKDHCJorueiS04wCsqHhiRDbbgITYAIgMKMFirgC2SSFmxrh7z9PzUqr0bK1HZ6Zn8vZVhETnyQ",
    "userHandle": "2HzoHm_hY0CjuEESY9tY6-3SdjmNHOoNqaPDcZGzsr0"
  }
}

טיפול בחריגים כשאין פרטי כניסה זמינים

במקרים מסוימים, יכול להיות שלמשתמש אין פרטי כניסה זמינים, או שהוא לא יביע הסכמה לשימוש בפרטי כניסה זמינים. אם מתבצעת קריאה ל-getCredential() ולא נמצאים פרטי כניסה, מוחזר NoCredentialException. במקרה כזה, הקוד צריך לטפל במופעים.NoCredentialException

coroutineScope {
  try {
    result = credentialManager.getCredential(
      context = activityContext,
      request = credentialRequest
    )
  } catch (e: GetCredentialException) {
    Log.e("CredentialManager", "No credential available", e)
  }
}PasskeyAndPasswordFunctions.kt

ב-Android מגרסה 14 ואילך, אפשר לקצר את זמן האחזור כשמציגים את בורר החשבונות באמצעות השיטה prepareGetCredential() לפני הקריאה ל-getCredential().

coroutineScope {
  val response = credentialManager.prepareGetCredential(
    GetCredentialRequest(
      listOf(
        getPublicKeyCredentialOption,
        getPasswordOption
      )
    )
  )
}PasskeyAndPasswordFunctions.kt

השיטה prepareGetCredential() לא מפעילה רכיבי ממשק משתמש. היא רק עוזרת לכם לבצע את עבודת ההכנה כדי שתוכלו להפעיל מאוחר יותר את הפעולה get-credential שנותרה (שכוללת ממשקי משתמש) דרך getCredential() API.

הנתונים שנשמרו במטמון מוחזרים באובייקט PrepareGetCredentialResponse. אם יש אישורי כניסה קיימים, התוצאות יישמרו במטמון, ואז תוכלו להפעיל את ממשק ה-API הנותר getCredential() כדי להציג את בורר החשבונות עם הנתונים ששמורים במטמון.

תהליכי הרשמה

אפשר לרשום משתמש לאימות באמצעות מפתח גישה או סיסמה.

יצירת מפתח גישה

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

suspend fun createPasskey(requestJson: String, preferImmediatelyAvailableCredentials: Boolean) {
  val createPublicKeyCredentialRequest = CreatePublicKeyCredentialRequest(
    // Contains the request in JSON format. Uses the standard WebAuthn
    // web JSON spec.
    requestJson = requestJson,
    // Defines whether you prefer to use only immediately available
    // credentials, not hybrid credentials, to fulfill this request.
    // This value is false by default.
    preferImmediatelyAvailableCredentials = preferImmediatelyAvailableCredentials,
  )

  // Execute CreateCredentialRequest asynchronously to register credentials
  // for a user account. Handle success and failure cases with the result and
  // exceptions, respectively.
  coroutineScope {
    try {
      val result = credentialManager.createCredential(
        // Use an activity-based context to avoid undefined system
        // UI launching behavior
        context = activityContext,
        request = createPublicKeyCredentialRequest,
      )
      //  Handle passkey creation result
    } catch (e : CreateCredentialException){
      handleFailure(e)
    }
  }
}PasskeyAndPasswordFunctions.kt

fun handleFailure(e: CreateCredentialException) {
  when (e) {
    is CreatePublicKeyCredentialDomException -> {
      // Handle the passkey DOM errors thrown according to the
      // WebAuthn spec.
    }
    is CreateCredentialCancellationException -> {
      // The user intentionally canceled the operation and chose not
      // to register the credential.
    }
    is CreateCredentialInterruptedException -> {
      // Retry-able error. Consider retrying the call.
    }
    is CreateCredentialProviderConfigurationException -> {
      // Your app is missing the provider configuration dependency.
      // Most likely, you're missing the
      // "credentials-play-services-auth" module.
    }
    is CreateCredentialCustomException -> {
      // You have encountered an error from a 3rd-party SDK. If you
      // make the API call with a request object that's a subclass of
      // CreateCustomCredentialRequest using a 3rd-party SDK, then you
      // should check for any custom exception type constants within
      // that SDK to match with e.type. Otherwise, drop or log the
      // exception.
    }
    else -> Log.w(TAG, "Unexpected exception type ${e::class.java.name}")
  }
}PasskeyAndPasswordFunctions.kt

בחירת הפורמט של בקשת ה-JSON

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

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

{
  "challenge": "abc123",
  "rp": {
    "name": "Credential Manager example",
    "id": "credential-manager-test.example.com"
  },
  "user": {
    "id": "def456",
    "name": "helloandroid@gmail.com",
    "displayName": "helloandroid@gmail.com"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "timeout": 1800000,
  "attestation": "none",
  "excludeCredentials": [
    {
      "id": "ghi789",
      "type": "public-key"
    },
    {
      "id": "jkl012",
      "type": "public-key"
    }
  ],
  "authenticatorSelection": {
    "authenticatorAttachment": "platform",
    "requireResidentKey": true,
    "residentKey": "required",
    "userVerification": "required"
  }
}

הגדרת ערכים ל-authenticatorAttachment

אפשר להגדיר את הפרמטר authenticatorAttachment רק בזמן יצירת פרטי הכניסה. אפשר לציין את הערכים platform,‏ cross-platform או לא לציין ערך. ברוב המקרים, מומלץ לא להזין ערך.

‫platform: כדי לרשום את המכשיר הנוכחי של המשתמש או להציג למשתמש סיסמה הנחיה לשדרוג למפתחות גישה אחרי כניסה לחשבון, מגדירים את authenticatorAttachment לערך platform.
‫cross-platform: הערך הזה משמש בדרך כלל כשרושמים אמצעי אימות רב-שלבי, ולא משמש בהקשר של מפתחות גישה.
ללא ערך: כדי לאפשר למשתמשים ליצור מפתחות גישה במכשירים המועדפים עליהם (לדוגמה, בהגדרות החשבון), לא צריך לציין את הפרמטר authenticatorAttachment כשמשתמש בוחר להוסיף מפתח גישה. ברוב המקרים, האפשרות הטובה ביותר היא לא לציין את הפרמטר.

מניעת יצירה של מפתחות גישה כפולים

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

טיפול בתגובת JSON

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

{
  "id": "KEDetxZcUfinhVi6Za5nZQ",
  "type": "public-key",
  "rawId": "KEDetxZcUfinhVi6Za5nZQ",
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoibmhrUVhmRTU5SmI5N1Z5eU5Ka3ZEaVh1Y01Fdmx0ZHV2Y3JEbUdyT0RIWSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
    "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViUj5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGRdAAAAAAAAAAAAAAAAAAAAAAAAAAAAEChA3rcWXFH4p4VYumWuZ2WlAQIDJiABIVgg4RqZaJyaC24Pf4tT-8ONIZ5_Elddf3dNotGOx81jj3siWCAWXS6Lz70hvC2g8hwoLllOwlsbYatNkO2uYFO-eJID6A"
  }
}

אימות המקור מ-JSON של נתוני לקוח

הערך origin מייצג את האפליקציה או האתר שממנו מגיעה הבקשה, והוא משמש את מפתחות הגישה להגנה מפני התקפות פישינג. השרת של האפליקציה צריך לבדוק את המקור של נתוני הלקוח מול רשימת ההיתרים של אפליקציות ואתרים מאושרים. אם השרת מקבל בקשה מאפליקציה או מאתר ממקור לא מוכר, הבקשה צריכה להידחות.

במקרה של אינטרנט, origin משקף מקור באותו אתר שבו בוצעה הכניסה באמצעות פרטי הכניסה. לדוגמה, אם כתובת ה-URL היא https://www.example.com:8443/store?category=shoes#athletic , אז origin הוא https://www.example.com:8443.

באפליקציות ל-Android, סוכן המשתמש מגדיר באופן אוטומטי את origin לחתימה של האפליקציה שקוראת ל-API. צריך לוודא שהחתימה תואמת בשרת כדי לאמת את האפליקציה שקוראת ל-Passkey API. ‫origin ב-Android הוא URI שנגזר מגיבוב SHA-256 של אישור החתימה של ה-APK, למשל:

android:apk-key-hash:<sha256_hash-of-apk-signing-cert>

אפשר למצוא את גיבובי ה-SHA-256 של אישורי החתימה ממאגר מפתחות על ידי הרצת פקודת הטרמינל הבאה:

keytool -list -keystore <path-to-apk-signing-keystore>

הגיבובים מסוג SHA-256 הם בפורמט הקסדצימלי עם תו מפריד של נקודתיים (91:F7:CB:F9:D6:81…), והערכים של Android origin הם בקידוד base64url. בדוגמה הזו של Python אפשר לראות איך להמיר את פורמט הגיבוב לפורמט הקסדצימלי תואם עם נקודתיים כמפריד:

import binascii
import base64
fingerprint = '91:F7:CB:F9:D6:81:53:1B:C7:A5:8F:B8:33:CC:A1:4D:AB:ED:E5:09:C5'
print("android:apk-key-hash:" + base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))

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

android:apk-key-hash:kffL-daBUxvHpY-4M8yhTavt5QnFEI2LsexohxrGPYU

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

שמירת סיסמה של משתמש

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

suspend fun registerPassword(username: String, password: String) {
  // Initialize a CreatePasswordRequest object.
  val createPasswordRequest =
    CreatePasswordRequest(id = username, password = password)

  // Create credential and handle result.
  coroutineScope {
    try {
      val result =
        credentialManager.createCredential(
          // Use an activity based context to avoid undefined
          // system UI launching behavior.
          activityContext,
          createPasswordRequest
        )
      // Handle register password result
    } catch (e: CreateCredentialException) {
      handleFailure(e)
    }
  }
}PasskeyAndPasswordFunctions.kt

תמיכה בשחזור פרטי כניסה

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

יצירה אוטומטית של מפתחות גישה למשתמשים

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

CreatePublicKeyCredentialRequest(
    // other parameters
    isConditionalCreateRequest: Boolean = true
)

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

כדי להשתמש בתכונה הזו צריך גרסה 1.6.0-alpha01 ומעלה.

הוספת תמיכה בכלי ניהול סיסמאות עם נקודות קצה של מפתחות גישה וכתובות URL מוכרות

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

לצד שלישי (relying party) בכתובת https://example.com, שיש לו אתר ואפליקציות ל-Android ול-iOS, כתובת ה-URL המוכרת תהיה https://example.com/.well-known/passkey-endpoints.

כשמבצעים שאילתה על כתובת ה-URL, התגובה צריכה להשתמש בסכימה הבאה

{
  "enroll": "https://example.com/account/manage/passkeys/create"
  "manage": "https://example.com/account/manage/passkeys"
}

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

עוזרים למשתמשים לנהל את מפתחות הגישה שלהם על ידי הצגת הספק שיצר אותם

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

לדוגמה, אם משתמש יוצר מפתח גישה במכשיר מבוסס-Android באמצעות מנהל הסיסמאות של Google, ספק שירותי ה-RP מקבל AAGUID שנראה בערך כך: ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4. הצד המסתמך יכול להוסיף הערה למפתח הגישה ברשימת מפתחות הגישה כדי לציין שהוא נוצר באמצעות מנהל הסיסמאות של Google.

כדי למפות AAGUID לספק מפתחות גישה, צדדים מסתמכים יכולים להשתמש במאגר AAGUID שמקורו בקהילה. מחפשים את ה-AAGUID ברשימה כדי למצוא את שם הספק של מפתח הגישה ואת הסמל שלו.

מידע נוסף על שילוב של AAGUID

פתרון בעיות נפוצות

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

מקורות מידע נוספים

למידע נוסף על Credential Manager API ומפתחות גישה, אפשר לעיין במקורות המידע הבאים: