從 FIDO2 遷移至憑證管理工具

如要在 Android 驗證，建議使用 Credential Manager，這個 API 支援密碼金鑰、聯合登入和第三方驗證服務供應器，可提供安全便利的環境，讓使用者同步處理及管理憑證。如果開發人員使用本機 FIDO2 憑證，應透過整合 Credential Manager API 更新應用程式，並支援密碼金鑰驗證機制。本文說明如何將專案從 FIDO2 遷移至 Credential Manager。

從 FIDO2 改用 Credential Manager 的原因

在大多數情況下，您應將 Android 應用程式的驗證服務供應器改用 Credential Manager。改用 Credential Manager 的原因包括：

• 支援密碼金鑰：Credential Manager 支援密碼金鑰，這種新的無密碼驗證機制比密碼更安全，也更容易使用。
• 多種登入方法：Credential Manager 支援多種登入方法，包括密碼、密碼金鑰和聯合登入方法。如此一來，無論使用者偏好的驗證方法為何，驗證程序都會更輕鬆。
• 支援第三方憑證提供者：在 Android 14 以上版本中，Credential Manager 可支援多個第三方憑證提供者。也就是說，使用者可透過其他提供者的現有憑證登入您的應用程式。
• 一致的使用者體驗：Credential Manager 可針對跨應用程式驗證和登入機制，提供更一致的使用者體驗。如此一來，使用者就能更輕鬆瞭解及使用應用程式驗證流程。

如要開始從 FIDO2 改用 Credential Manager，請按照下列步驟操作。

更新依附元件

1. 將專案 build.gradle 檔案中的 Kotlin 外掛程式更新為 1.8.10 以上版本。

   plugins {
     //…
       id 'org.jetbrains.kotlin.android' version '1.8.10' apply false
     //…
   }
   

2. 在專案 build.gradle 檔案中更新依附元件，以便使用 Credential Manager 和 Play 服務驗證功能。

   dependencies {
     // ...
     // Credential Manager:
     implementation 'androidx.credentials:credentials:<latest-version>'
   
     // Play Services Authentication:
     // Optional - needed for credentials support from play services, for devices running
     // Android 13 and below:
     implementation 'androidx.credentials:credentials-play-services-auth:<latest-version>'
     // ...
   }
   

3. 以 Credential Manager 初始化取代 FIDO 初始化。請在用於建立密碼金鑰及登入方法的類別中，加入這項宣告：

   val credMan = CredentialManager.create(context)
   

建立密碼金鑰

您需要建立新的密碼金鑰、將金鑰與使用者帳戶建立關聯，並將該金鑰的公開金鑰儲存在伺服器上，使用者才能利用這組金鑰登入。更新註冊函式呼叫後，即可設定應用程式的這項功能。

1. 如要在建立密碼金鑰時取得傳送至 createCredential() 方法的必要參數，請按照 WebAuthn 規格說明所述，將 name("residentKey").value("required") 新增至您的 registerRequest() 伺服器呼叫。

   suspend fun registerRequest(sessionId: String ... {
       // ...
       .method("POST", jsonRequestBody {
           name("attestation").value("none")
           name("authenticatorSelection").objectValue {
               name("residentKey").value("required")
           }
       }).build()
       // ...
   }
   

2. 將 registerRequest() 和所有子項函式的 return 類型設為 JSONObject。

   suspend fun registerRequest(sessionId: String): ApiResult<JSONObject> {
       val call = client.newCall(
           Request.Builder()
               .url("$BASE_URL/<your api url>")
               .addHeader("Cookie", formatCookie(sessionId))
               .method("POST", jsonRequestBody {
                   name("attestation").value("none")
                   name("authenticatorSelection").objectValue {
                       name("authenticatorAttachment").value("platform")
                       name("userVerification").value("required")
                       name("residentKey").value("required")
                   }
               }).build()
       )
       val response = call.await()
       return response.result("Error calling the api") {
           parsePublicKeyCredentialCreationOptions(
               body ?: throw ApiException("Empty response from the api call")
           )
       }
   }
   

3. 從檢視畫面中，安全地移除處理意圖啟動器和活動結果呼叫的方法。

4. registerRequest() 現在會傳回 JSONObject，因此不需要建立 PendingIntent。將傳回的意圖替換為 JSONObject。更新意圖啟動器呼叫，以便從 Credential Manager API 呼叫 createCredential()。呼叫 createCredential() API 方法。

   suspend fun createPasskey(
       activity: Activity,
       requestResult: JSONObject
       ): CreatePublicKeyCredentialResponse? {
           val request = CreatePublicKeyCredentialRequest(requestResult.toString())
           var response: CreatePublicKeyCredentialResponse? = null
           try {
               response = credMan.createCredential(
                   request as CreateCredentialRequest,
                   activity
               ) as CreatePublicKeyCredentialResponse
           } catch (e: CreateCredentialException) {
   
               showErrorAlert(activity, e)
   
               return null
           }
           return response
       }
   

5. 呼叫成功後，請將回應傳回伺服器。這個呼叫的要求和回應類似於 FIDO2 實作項目，因此不必修改。

使用密碼金鑰驗證

設定密碼金鑰建立程序後，您可以調整應用程式設定，讓使用者能使用自己的密碼金鑰登入並進行驗證。如要這麼做，您需要更新驗證碼來處理 Credential Manager 結果，並實作函式，透過密碼金鑰驗證。

1. 為了取得傳送至 getCredential() 要求的必要資訊，您需要向伺服器發出登入要求呼叫，而該呼叫與 FIDO2 實作項目相同，因此不必修改。

2. 與註冊要求呼叫類似，傳回的回應會採用 JSONObject 格式。

   /**
    * @param sessionId The session ID to be used for the sign-in.
    * @param credentialId The credential ID of this device.
    * @return a JSON object.
    */
   suspend fun signinRequest(): ApiResult<JSONObject> {
       val call = client.newCall(Builder().url(buildString {
           append("$BASE_URL/signinRequest")
       }).method("POST", jsonRequestBody {})
           .build()
       )
       val response = call.await()
       return response.result("Error calling /signinRequest") {
           parsePublicKeyCredentialRequestOptions(
               body ?: throw ApiException("Empty response from /signinRequest")
           )
       }
   }
   
   /**
    * @param sessionId The session ID to be used for the sign-in.
    * @param response The JSONObject for signInResponse.
    * @param credentialId id/rawId.
    * @return A list of all the credentials registered on the server,
    * including the newly-registered one.
    */
   suspend fun signinResponse(
       sessionId: String, response: JSONObject, credentialId: String
       ): ApiResult<Unit> {
   
           val call = client.newCall(
               Builder().url("$BASE_URL/signinResponse")
                   .addHeader("Cookie",formatCookie(sessionId))
                   .method("POST", jsonRequestBody {
                       name("id").value(credentialId)
                       name("type").value(PUBLIC_KEY.toString())
                       name("rawId").value(credentialId)
                       name("response").objectValue {
                           name("clientDataJSON").value(
                               response.getString("clientDataJSON")
                           )
                           name("authenticatorData").value(
                               response.getString("authenticatorData")
                           )
                           name("signature").value(
                               response.getString("signature")
                           )
                           name("userHandle").value(
                               response.getString("userHandle")
                           )
                       }
                   }).build()
           )
           val apiResponse = call.await()
           return apiResponse.result("Error calling /signingResponse") {
           }
       }
   

3. 從檢視畫面中，安全地移除處理意圖啟動器和活動結果呼叫的方法。

4. signInRequest() 現在會傳回 JSONObject，因此不需要建立 PendingIntent。請將傳回的意圖替換為 JSONObject，並從 API 方法呼叫 getCredential()。

   suspend fun getPasskey(
       activity: Activity,
       creationResult: JSONObject
       ): GetCredentialResponse? {
           Toast.makeText(
               activity,
               "Fetching previously stored credentials",
               Toast.LENGTH_SHORT)
               .show()
           var result: GetCredentialResponse? = null
           try {
               val request= GetCredentialRequest(
                   listOf(
                       GetPublicKeyCredentialOption(
                           creationResult.toString(),
                           null
                       ),
                       GetPasswordOption()
                   )
               )
               result = credMan.getCredential(activity, request)
               if (result.credential is PublicKeyCredential) {
                   val publicKeycredential = result.credential as PublicKeyCredential
                   Log.i("TAG", "Passkey ${publicKeycredential.authenticationResponseJson}")
                   return result
               }
           } catch (e: Exception) {
               showErrorAlert(activity, e)
           }
           return result
       }
   

5. 呼叫成功後，請將回應傳回伺服器，方便確認及驗證使用者。這個 API 呼叫的要求和回應參數類似於 FIDO2 實作項目，因此不必修改。

其他資源

• Credential Manager 參考範例
• Credential Manager 程式碼研究室
• 透過 Credential Manager API，使用密碼金鑰在應用程式中提供順暢的驗證機制
• FIDO2 程式碼研究室