透過憑證管理工具讓使用者登入

Credential Manager 是全新的 Jetpack API，可在單一 API 中支援多種登入方式，像是使用者名稱/密碼、密碼金鑰和聯合登入解決方案 (例如使用 Google 帳戶登入)，因此可為開發人員簡化整合作業。

此外，不論使用者的驗證方法為何，Credential Manager 都能讓使用者透過單一登入介面登入，因此使用者可以更輕鬆簡便地登入應用程式。

本頁面說明密碼金鑰的概念，以及如何使用 Credential Manager API，針對密碼金鑰等驗證解決方案實作用戶端支援功能。您也可以查看另外的常見問題頁面，瞭解更詳細具體的問題與解答。

關於密碼金鑰

密碼金鑰比密碼更加安全方便。密碼金鑰可讓使用者透過生物特徵辨識感應器 (例如指紋或臉部辨識)、PIN 碼或解鎖圖案登入應用程式和網站。這麼做可以提供流暢的登入體驗，讓使用者不必記憶使用者名稱或密碼。

密碼金鑰採用 WebAuthn (網路驗證)，這是由 FIDO 聯盟和全球資訊網協會 (World Wide Web Consortium，W3C) 共同制定的標準。WebAuthn 使用公開金鑰密碼編譯機制來驗證使用者。使用者登入的網站或應用程式可以查看及儲存公開金鑰，但無法查看及儲存私密金鑰。私密金鑰會妥善保密，確保安全無虞。由於金鑰是獨一無二的，且與網站或應用程式綁定，因此密碼金鑰不會遭到網路釣魚攻擊，可提升安全性。

Credential Manager 可讓使用者建立密碼金鑰，並且儲存在 Google 密碼管理工具中。

如要瞭解如何使用 Credential Manager 實作順暢的密碼金鑰驗證流程，請參閱「使用密碼金鑰驗證使用者」一文。

必要條件

如要使用 Credential Manager，請完成本節中的步驟。

使用最新的平台版本

Android 4.4 (API 級別 19) 以上版本都支援 Credential Manager。

為應用程式新增依附元件

請將下列依附元件新增至應用程式模組的建構指令碼：

    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)

保留 ProGuard 檔案中的類別

在模組的 proguard-rules.pro 檔案中，新增下列指令：

-if class androidx.credentials.CredentialManager -keep class androidx.credentials.playservices.** {   *; }

如要進一步瞭解如何縮減、模糊化及最佳化應用程式，請參閱這篇文章。

新增 Digital Asset Links 的支援

如要讓 Android 應用程式支援密碼金鑰，請將應用程式與應用程式所擁有的網站建立關聯。如要宣告此關聯，請完成下列步驟：

  1. 建立 Digital Asset Links JSON 檔案。舉例來說，如要宣告網站 https://signin.example.com 和含有套件名稱 com.example 的 Android 應用程式可以共用登入憑證，請建立名為 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

    網站網址，格式為 https://domain[:optional_port]，例如 https://www.example.com。

    domain 必須完整，且使用 HTTPS 的通訊埠 443 時必須省略 optional_port。

    site 指定目標只能是根網域：您無法限制應用程式與特定子目錄建立關聯。請勿在網址中加入路徑，例如結尾的斜線。

    系統不會將子網域視為相符項目：也就是說，如果將 domain 指定為 www.example.com，網域 www.counter.example.com 就不會與您的應用程式建立關聯。

    下列欄位可用來識別 Android 應用程式：

    namespace android_app
    package_name 應用程式資訊清單中宣告的套件名稱。例如：com.example.android
    sha256_cert_fingerprints 應用程式簽署憑證的 SHA256 指紋。

  2. 請在登入網域的以下位置代管 Digital Assets Link JSON 檔案：

    https://domain[:optional_port]/.well-known/assetlinks.json

    舉例來說，如果您的登入網域為 signin.example.com，請在 https://signin.example.com/.well-known/assetlinks.json 上代管 JSON 檔案。

    Digital Assets Link 檔案的 MIME 類型必須為 JSON。確認伺服器會在回應中傳送 Content-Type: application/json 標頭。

  3. 確保主機允許 Google 擷取您的 Digital Asset Link 檔案。如果您有 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 檔案。您必須逸出在字串中使用的所有撇號和引號。例如：

    <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 和第三方憑證提供者使用，同時協助自動填入服務提供更符合需求的自動填入建議。應用程式使用 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 以上版本中，您可以在呼叫 getCredential() 前使用 prepareGetCredential() 方法，縮短顯示帳戶選取器的延遲時間。

Kotlin

val response = credentialManager.prepareGetCredential(   GetCredentialRequest(     listOf(       <getPublicKeyCredentialOption>,       <getPasswordOption>     )   ) }

Java

GetCredentialResponse response = credentialManager.prepareGetCredential(   new GetCredentialRequest(     Arrays.asList(       new PublicKeyCredentialOption(),       new PasswordOption()     )   ) );

prepareGetCredential() 方法不會叫用 UI 元素。它只能協助您執行準備工作，以便之後透過 getCredential() API 啟動其餘的憑證取得作業 (涉及 UI)。

快取的資料會在 PrepareGetCredentialResponse 物件中傳回。如果已有憑證，系統會快取結果，接著您可以在稍後啟動其餘的 getCredential() API，執行含有快取資料的帳戶選取器。

註冊流程

您可以使用密碼金鑰或密碼註冊使用者，以進行驗證程序。

建立密碼金鑰

如果想為使用者提供註冊密碼金鑰的選項，並允許他們使用密碼金鑰重新驗證，請使用 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": "[email protected]",     "displayName": "[email protected]"   },   "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 陣列中列出憑證 ID，以免在使用相同密碼金鑰供應器時，建立新的密碼金鑰。

處理 JSON 回應

下列程式碼片段顯示建立公開金鑰憑證的 JSON 回應範例。進一步瞭解如何處理傳回的公開金鑰憑證。

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

驗證用戶端資料 JSON 的來源

origin 代表要求的來源應用程式或網站，密碼金鑰會使用這個參數防範網路釣魚攻擊。應用程式的伺服器必須依據核准的應用程式和網站許可清單，檢查用戶端資料來源。如果伺服器收到不明來源的應用程式或網站發出的要求，則應拒絕要求。

如果是網頁，origin 會反映憑證登入網站的相同網站來源。例如，假設網址為 https://www.example.com:8443/store?category=shoes#athletic，則 origin 為 https://www.example.com:8443。

如果是 Android 應用程式，使用者代理程式會自動將 origin 設為呼叫應用程式的簽章。此簽章的驗證結果必須與應用程式伺服器上的許可清單比對相符，才能驗證密碼金鑰 API 的呼叫端。Android origin 是衍生自 APK 簽署憑證 SHA-256 雜湊的 URI，例如：

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

執行下列終端機指令，即可從 KeyStore 找到簽署憑證的 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 物件：

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 密碼管理工具中的密碼金鑰安全性》(Security of Passkeys in the Google Password Manager) 網誌文章中的「復原存取權或新增裝置」(Recovering access or adding new devices) 一節。

支援使用密碼金鑰端點已知網址的密碼管理工具

為了與密碼和 Credential Manager 工具完美整合，並提升日後的相容性，建議您新增密碼金鑰端點已知網址的支援功能。這是開放式的通訊協定，供聯盟中各方正式宣傳自家對密碼金鑰的支援，並提供註冊及管理密碼金鑰的直接連結。

  1. 如果您是 https://example.com 的依賴方，且擁有網站和 Android 和 iOS 應用程式，則已知網址會是 https://example.com/.well-known/passkey-endpoints。

  2. 使用者查詢該網址時，回應應採用下列結構定義：

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

  3. 如要直接在應用程式中 (而非在網頁上) 開啟這個連結，請使用 Android 應用程式連結。

  4. 詳情請參閱 GitHub 的密碼金鑰端點已知網址說明文件。

顯示建立密碼金鑰的供應商，協助使用者管理密碼金鑰

使用者在管理與特定應用程式相關聯的多個密碼金鑰時，會面臨一個挑戰，就是要找出要編輯或刪除的正確密碼金鑰。為協助解決這個問題，建議應用程式和網站在應用程式設定畫面的密碼金鑰清單中，加入其他資訊，例如建立憑證的供應商、建立日期和上次使用日期。您可以檢查與對應密碼金鑰相關聯的 AAGUID，取得供應商資訊。AAGUID 可在密碼金鑰的驗證工具資料中找到。

舉例來說，如果使用者在 Android 裝置上使用 Google 密碼管理工具建立密碼金鑰，則 RP 會收到 AAGUID，格式如下："ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4"。依賴方可以在密碼金鑰清單中加上註解，指出密碼金鑰是使用 Google 密碼管理工具建立的。

如要將 AAGUID 對應至密碼金鑰供應器，RP 可以使用社群來源的 AAGUID 存放區。在清單中查詢 AAGUID，找出密碼金鑰提供者名稱和圖示。

進一步瞭解 AAGUID 整合。

排解常見錯誤

如要瞭解常見的錯誤代碼、說明和原因，請參閱 憑證管理工具疑難排解指南。

其他資源

如要進一步瞭解 Credential Manager API 和密碼金鑰，請參閱下列資源：