Credential Manager הוא ממשק API של Jetpack שתומך בכמה שיטות כניסה, כמו שם משתמש וסיסמה, מפתחות גישה ופתרונות של כניסה מאוחדת (כמו 'כניסה באמצעות חשבון Google') בממשק API אחד, וכך מפשט את השילוב למפתחים.
בנוסף, עבור המשתמשים, מנהל פרטי הכניסה מאחד את ממשק הכניסה בכל שיטות האימות, כדי שלמשתמשים יהיה קל יותר להיכנס לאפליקציות בכל שיטה שבה בחרו להשתמש.
בדף הזה מוסבר מהם מפתחות גישה ואיך מטמיעים תמיכה בצד הלקוח לפתרונות אימות, כולל מפתחות גישה, באמצעות Credential Manager API. יש גם דף שאלות נפוצות נפרד שבו מוצגות תשובות לשאלות מפורטות וספציפיות יותר.
המשוב שלכם הוא חלק חיוני בשיפור ה-Credential Manager API. אתם יכולים לשלוח לנו בעיות שמצאתם או רעיונות לשיפור ה-API באמצעות הקישור הבא:
מידע על מפתחות גישה
מפתחות גישה הם תחליף בטוח וקל יותר לסיסמאות. עם מפתחות גישה, משתמשים יכולים להיכנס לאפליקציות ולאתרים באמצעות חיישן ביומטרי (כמו טביעת אצבע או זיהוי פנים), קוד אימות או קו ביטול נעילה. כך המשתמשים יכולים להיכנס לחשבון בקלות, בלי לזכור שמות משתמשים או סיסמאות.
מפתחות הגישה מבוססים על WebAuthn (אימות אינטרנט), תקן שפותח במשותף על ידי FIDO Alliance ו-World Wide Web Consortium (W3C). ב-WebAuthn נעשה שימוש בקריפטוגרפיה של מפתח ציבורי כדי לאמת את המשתמש. האתר או האפליקציה שבהם המשתמש נכנס לחשבון יכולים לראות ולאחסן את המפתח הציבורי, אבל אף פעם לא את המפתח הפרטי. המפתח הפרטי נשמר בסודיות ובבטחה. בגלל שהמפתח ייחודי ומקושר לאתר או לאפליקציה, אי אפשר לבצע פישינג באמצעות מפתחות גישה, וכך מגבירה את האבטחה.
Credential Manager מאפשר למשתמשים ליצור מפתחות גישה ולאחסן אותם במנהל הסיסמאות של Google.
במאמר אימות משתמשים באמצעות מפתחות גישה מוסבר איך מטמיעים תהליכי אימות חלקים באמצעות מפתחות גישה באמצעות Credential Manager.
דרישות מוקדמות
בקטע הזה מוסבר איך להשתמש ב'מנהל פרטי הכניסה'.
שימוש בגרסה עדכנית של הפלטפורמה
יש תמיכה ב-Credential Manager ב-Android 4.4 (רמת API 19) ואילך.
הוספת יחסי תלות לאפליקציה
מוסיפים את יחסי התלות הבאים לסקריפט ה-build של מודול האפליקציה:
Kotlin
dependencies { implementation("androidx.credentials:credentials:1.5.0-alpha05") // optional - needed for credentials support from play services, for devices running // Android 13 and below. implementation("androidx.credentials:credentials-play-services-auth:1.5.0-alpha05") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.5.0-alpha05" // optional - needed for credentials support from play services, for devices running // Android 13 and below. implementation "androidx.credentials:credentials-play-services-auth:1.5.0-alpha05" }
שמירה של הכיתות בקובץ ProGuard
לקובץ proguard-rules.pro
של המודול, מוסיפים את ההוראות הבאות:
-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
*;
}
UnsupportedOperationException("Post-U not supported yet")
איך מצמצמים, מטשטשים ומבצעים אופטימיזציה של האפליקציה
הוספת תמיכה בקישורים לנכסים דיגיטליים
כדי להפעיל תמיכה במפתחות גישה באפליקציה ל-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 ] } } ]
השדה
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 Assets Link במיקום הבא בדומיין הכניסה:
https://domain[:optional_port]/.well-known/assetlinks.json
לדוגמה, אם הדומיין של כניסה הוא
signin.example.com
, מארחים את קובץ ה-JSON בכתובתhttps://signin.example.com/.well-known/assetlinks.json
.סוג ה-MIME של הקובץ Digital Asset Link צריך להיות JSON. מוודאים שהשרת שולח בתגובה את הכותרת
Content-Type: application/json
.מוודאים שהמארח מאפשר ל-Google לאחזר את הקובץ של Digital Asset Links. אם יש לכם קובץ
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>
> 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
הגדרת Credential Manager
כדי להגדיר ולאתחל אובייקט CredentialManager
, מוסיפים לוגיקה דומה לזו:
Kotlin
// Use your app or activity context to instantiate a client instance of // CredentialManager. val credentialManager = CredentialManager.create(context)
Java
// Use your app or activity context to instantiate a client instance of // CredentialManager. CredentialManager credentialManager = CredentialManager.create(context)
ציון שדות של פרטי כניסה
ב-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"
...
/>
כניסה של המשתמש
כדי לאחזר את כל האפשרויות של מפתחות הגישה והסיסמאות שמשויכות לחשבון המשתמש, מבצעים את השלבים הבאים:
מאתחלים את אפשרויות האימות של הסיסמה ומפתח הגישה:
Kotlin
// 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 )
Java
// Retrieves the user's saved password for your app from their // password provider. GetPasswordOption getPasswordOption = new GetPasswordOption(); // Get passkey from the user's public key credential provider. GetPublicKeyCredentialOption getPublicKeyCredentialOption = new GetPublicKeyCredentialOption(requestJson);
משתמשים באפשרויות שאוחזרו מהשלב הקודם כדי ליצור את בקשת הכניסה.
Kotlin
val getCredRequest = GetCredentialRequest( listOf(getPasswordOption, getPublicKeyCredentialOption) )
Java
GetCredentialRequest getCredRequest = new GetCredentialRequest.Builder() .addCredentialOption(getPasswordOption) .addCredentialOption(getPublicKeyCredentialOption) .build();
מפעילים את תהליך הכניסה:
Kotlin
coroutineScope.launch { try { val result = credentialManager.getCredential( // Use an activity-based context to avoid undefined system UI // launching behavior. context = activityContext, request = getCredRequest ) handleSignIn(result) } catch (e : GetCredentialException) { handleFailure(e) } } 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") } } }
Java
credentialManager.getCredentialAsync( // Use activity based context to avoid undefined // system UI launching behavior activity, getCredRequest, cancellationSignal, <executor>, new CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() { @Override public void onResult(GetCredentialResponse result) { handleSignIn(result); } @Override public void onError(GetCredentialException e) { handleFailure(e); } } ); public void handleSignIn(GetCredentialResponse result) { // Handle the successfully returned credential. Credential credential = result.getCredential(); if (credential instanceof PublicKeyCredential) { String responseJson = ((PublicKeyCredential) credential).getAuthenticationResponseJson(); // Share responseJson i.e. a GetCredentialResponse on your server to validate and authenticate } else if (credential instanceof PasswordCredential) { String username = ((PasswordCredential) credential).getId(); String password = ((PasswordCredential) credential).getPassword(); // Use id and password to send to your server to validate and authenticate } else if (credential instanceof CustomCredential) { if (ExampleCustomCredential.TYPE.equals(credential.getType())) { try { ExampleCustomCredential customCred = ExampleCustomCredential.createFrom(customCredential.getData()); // Extract the required credentials and complete the // authentication as per the federated sign in or any external // sign in library flow } catch (ExampleCustomCredential.ExampleCustomCredentialParsingException e) { // 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"); } }
בדוגמה הבאה מוסבר איך לעצב את בקשת ה-JSON כשמקבלים מפתח גישה:
{
"challenge": "T1xCsnxM2DNL2KdK5CLa6fMhD7OBqho6syzInk_n-Uo",
"allowCredentials": [],
"timeout": 1800000,
"userVerification": "required",
"rpId": "credential-manager-app-test.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
.
Kotlin
try {
val credential = credentialManager.getCredential(credentialRequest)
} catch (e: NoCredentialException) {
Log.e("CredentialManager", "No credential available", e)
}
Java
try {
Credential credential = credentialManager.getCredential(credentialRequest);
} catch (NoCredentialException e) {
Log.e("CredentialManager", "No credential available", e);
}
ב-Android מגרסה 14 ואילך, אפשר לקצר את זמן האחזור כשמציגים את בורר החשבונות באמצעות השיטה prepareGetCredential()
לפני שמתקשרים ל-getCredential()
.
Kotlin
val response = credentialManager.prepareGetCredential(
GetCredentialRequest(
listOf(
<getPublicKeyCredentialOption>,
<getPasswordOption>
)
)
}
Java
GetCredentialResponse response = credentialManager.prepareGetCredential(
new GetCredentialRequest(
Arrays.asList(
new PublicKeyCredentialOption(),
new PasswordOption()
)
)
);
השיטה prepareGetCredential()
לא מפעילה רכיבי ממשק משתמש. הוא רק עוזר לכם לבצע את עבודת ההכנה כדי שתוכלו להפעיל מאוחר יותר את שאר הפעולות של get-credential (שכוללות ממשקי משתמש) דרך ה-API של getCredential()
.
הנתונים שנשמרו במטמון מוחזרים באובייקט PrepareGetCredentialResponse
. אם יש פרטי כניסה קיימים, התוצאות יישמרו במטמון ובהמשך אפשר יהיה להפעיל את שאר ממשק ה-API של getCredential()
כדי להעלות את בורר החשבונות עם הנתונים שנשמרו במטמון.
תהליכי רישום
אפשר לרשום משתמש לאימות באמצעות מפתח גישה או סיסמה.
יצירת מפתח גישה
כדי לתת למשתמשים אפשרות לרשום מפתח גישה ולהשתמש בו לאימות מחדש, צריך לרשום את פרטי הכניסה של המשתמש באמצעות אובייקט CreatePublicKeyCredentialRequest
.
Kotlin
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.launch { try { val result = credentialManager.createCredential( // Use an activity-based context to avoid undefined system // UI launching behavior context = activityContext, request = createPublicKeyCredentialRequest, ) handlePasskeyRegistrationResult(result) } catch (e : CreateCredentialException){ handleFailure(e) } } } fun handleFailure(e: CreateCredentialException) { when (e) { is CreatePublicKeyCredentialDomException -> { // Handle the passkey DOM errors thrown according to the // WebAuthn spec. handlePasskeyError(e.domError) } 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 CreateCredentialUnknownException -> ... 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}") } }
Java
public void createPasskey(String requestJson, boolean preferImmediatelyAvailableCredentials) { CreatePublicKeyCredentialRequest createPublicKeyCredentialRequest = // `requestJson` contains the request in JSON format. Uses the standard // WebAuthn web JSON spec. // `preferImmediatelyAvailableCredentials` defines whether you prefer // to only use immediately available credentials, not hybrid credentials, // to fulfill this request. This value is false by default. new CreatePublicKeyCredentialRequest( requestJson, preferImmediatelyAvailableCredentials); // Execute CreateCredentialRequest asynchronously to register credentials // for a user account. Handle success and failure cases with the result and // exceptions, respectively. credentialManager.createCredentialAsync( // Use an activity-based context to avoid undefined system // UI launching behavior requireActivity(), createPublicKeyCredentialRequest, cancellationSignal, executor, new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() { @Override public void onResult(CreateCredentialResponse result) { handleSuccessfulCreatePasskeyResult(result); } @Override public void onError(CreateCredentialException e) { if (e instanceof CreatePublicKeyCredentialDomException) { // Handle the passkey DOM errors thrown according to the // WebAuthn spec. handlePasskeyError(((CreatePublicKeyCredentialDomException)e).getDomError()); } else if (e instanceof CreateCredentialCancellationException) { // The user intentionally canceled the operation and chose not // to register the credential. } else if (e instanceof CreateCredentialInterruptedException) { // Retry-able error. Consider retrying the call. } else if (e instanceof CreateCredentialProviderConfigurationException) { // Your app is missing the provider configuration dependency. // Most likely, you're missing the // "credentials-play-services-auth" module. } else if (e instanceof CreateCredentialUnknownException) { } else if (e instanceof 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.getClass().getName()); } } } ); }
עיצוב הבקשה בפורמט 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
: הערך הזה משמש לעיתים קרובות כשרושמים פרטי כניסה רב-שלביים, ולא נעשה בו שימוש בהקשר של מפתח גישה.- No value: כדי לאפשר למשתמשים ליצור מפתחות גישה במכשירים המועדפים עליהם (למשל, בהגדרות החשבון), אסור לציין את הפרמטר
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 של מפתח הגישה. הערך של Android origin
הוא URI שמבוסס על הגיבוב (hash) של 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 מוסבר איך להמיר את פורמט ה-hash לפורמט הקסדצימלי תואם שמופרד בפסיקים:
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
:
Kotlin
fun registerPassword(username: String, password: String) { // Initialize a CreatePasswordRequest object. val createPasswordRequest = CreatePasswordRequest(id = username, password = password) // Create credential and handle result. coroutineScope.launch { try { val result = credentialManager.createCredential( // Use an activity based context to avoid undefined // system UI launching behavior. activityContext, createPasswordRequest ) handleRegisterPasswordResult(result) } catch (e: CreateCredentialException) { handleFailure(e) } } }
Java
void registerPassword(String username, String password) { // Initialize a CreatePasswordRequest object. CreatePasswordRequest createPasswordRequest = new CreatePasswordRequest(username, password); // Register the username and password. credentialManager.createCredentialAsync( // Use an activity-based context to avoid undefined // system UI launching behavior requireActivity(), createPasswordRequest, cancellationSignal, executor, new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() { @Override public void onResult(CreateCredentialResponse result) { handleResult(result); } @Override public void onError(CreateCredentialException e) { handleFailure(e); } } ); }
תמיכה בשחזור פרטי כניסה
אם למשתמש כבר אין גישה למכשיר שבו אחסנו את פרטי הכניסה, יכול להיות שהוא יצטרך לשחזר נתונים מגיבוי מאובטח אונליין. מידע נוסף על תמיכה בתהליך שחזור פרטי הכניסה זמין בקטע 'שחזור הגישה או הוספת מכשירים חדשים' בפוסט הזה בבלוג: אבטחת מפתחות הגישה במנהל הסיסמאות של Google.
הוספת תמיכה בכלים לניהול סיסמאות עם כתובות URL ידועות של נקודות קצה של מפתחות גישה
כדי לאפשר שילוב חלק ותאימות עתידית לכלים לניהול סיסמאות ופרטי כניסה, מומלץ להוסיף תמיכה בכתובות URL ידועות של נקודות קצה של מפתחות גישה. זהו פרוטוקול פתוח שמאפשר לצדדים שתומכים במפתחות גישה לפרסם באופן רשמי את התמיכה שלהם במפתחות גישה ולספק קישורים ישירים להרשמה ולניהול של מפתחות גישה.
- עבור צד נסמך בכתובת
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 ברשימה כדי למצוא את השם והסמל של הספק של מפתח הגישה.
פתרון של שגיאות נפוצות
במדריך לפתרון בעיות ב-Credential Manager מפורטים קודי שגיאות נפוצים, תיאורים ומידע על הסיבות שלהם.
מקורות מידע נוספים
למידע נוסף על Credential Manager API ומפתחות גישה, תוכלו לעיין במקורות המידע הבאים:
- מדריך בנושא חוויית המשתמש במפתחות גישה
- סרטון: איך להפחית את ההסתמכות על סיסמאות באפליקציות ל-Android עם תמיכה במפתחות גישה
- Codelab: איך מפשטים את תהליכי האימות באמצעות Credential Manager API באפליקציות ל-Android
- אפליקציה לדוגמה: CredentialManager