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

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

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

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

המשוב שלכם הוא חלק חיוני בשיפור ה-Credential Manager API. אתם יכולים לשלוח לנו בעיות שמצאתם או רעיונות לשיפור ה-API באמצעות הקישור הבא:

שליחת משוב

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

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

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

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

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

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

כדי להשתמש ב-Credential Manager, מבצעים את השלבים שמפורטים בקטע הזה.

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

יש תמיכה ב-Credential Manager ב-Android 4.4 (רמת API 19) ואילך.

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

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-beta01")

    // 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-beta01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.5.0-beta01"

    // 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-beta01"
}

שמירה של הכיתות בקובץ ProGuard

מוסיפים את ההוראות הבאות לקובץ proguard-rules.pro של המודול:

-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
  *;
}
UnsupportedOperationException("Post-U not supported yet")

איך מצמצמים, מטשטשים ומבצעים אופטימיזציה של האפליקציה

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

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

  1. יוצרים קובץ 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 של אישור החתימה של האפליקציה.

  2. מארחים את קובץ ה-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 בתגובה.

  3. מוודאים שהמארח מאפשר ל-Google לאחזר את הקובץ של Digital Asset Links. אם יש לכם קובץ robots.txt, הוא חייב לאפשר לסוכן Googlebot לאחזר את /.well-known/assetlinks.json. ברוב האתרים אפשר לאפשר לכל סוכן אוטומטי לאחזר קבצים בנתיב /.well-known/, כדי ששירותים אחרים יוכלו לגשת למטא-נתונים בקבצים האלה:

    User-agent: *
Allow: /.well-known/

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

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

  5. אם אתם משתמשים בכניסה באמצעות סיסמה דרך 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"
...
 />

כניסה של המשתמש

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

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

    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);

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

    Kotlin

    val getCredRequest = GetCredentialRequest(
    listOf(getPasswordOption, getPublicKeyCredentialOption)
)

    Java

    GetCredentialRequest getCredRequest = new GetCredentialRequest.Builder()
    .addCredentialOption(getPasswordOption)
    .addCredentialOption(getPublicKeyCredentialOption)
    .build();

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

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

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

  1. לצד שלישי נסמך בכתובת https://example.com, שיש לו אתר וגם אפליקציות ל-Android ול-iOS, כתובת ה-URL המוכרת תהיה https://example.com/.well-known/passkey-endpoints.

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

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

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

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

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

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

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

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

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

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

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

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

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