使用 Credential Manager 實作還原憑證功能

本頁說明如何建立、登入及刪除還原金鑰。

版本相容性

如要使用 Credential Manager 的「還原憑證」功能，裝置必須搭載 Android 9 以上版本、Google Play 服務 (GMS) 核心 24220000 以上版本，以及 androidx.credentials 程式庫 1.5.0 以上版本。

必要條件

設定類似密碼金鑰伺服器的信賴憑證者伺服器。 如果已設定伺服器來處理密碼金鑰驗證，請使用相同的伺服器端實作方式來還原金鑰。

注意： 密碼金鑰和還原金鑰的伺服器端實作方式相同，但用戶端應用程式可以支援還原金鑰，不必支援密碼金鑰。由於還原金鑰的運作方式與應用程式中的驗證方法 (例如密碼或使用 Google 帳戶登入) 無關，因此您不需要對應用程式程式碼中的現有驗證方法進行任何額外變更。

依附元件

在應用程式模組的 build.gradle 檔案中新增下列依附元件：

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

androidx.credentials 程式庫 1.5.0 以上版本提供「還原憑證」功能。不過，建議您盡可能使用最新穩定版本的依附元件。

注意： 無論 manifest 中是否設定 allowBackup，還原憑證功能都能正常運作。

總覽

1. 建立還原金鑰：如要建立還原金鑰，請完成下列步驟：
   1. 建立 Credential Manager 執行個體：建立 CredentialManager 物件。
   2. 從應用程式伺服器取得憑證建立選項：從應用程式伺服器將建立還原金鑰所需的詳細資料傳送至用戶端應用程式。
   3. 建立還原金鑰：如果使用者已登入應用程式，請為使用者帳戶建立還原金鑰。
   4. 處理憑證建立回應：將憑證從用戶端應用程式傳送至應用程式伺服器進行處理，並處理任何例外狀況。
2. 使用復原金鑰登入：如要使用復原金鑰登入，請完成下列步驟：
   1. 從應用程式伺服器取得憑證擷取選項：將從應用程式伺服器擷取還原金鑰所需的詳細資料傳送給用戶端應用程式。
   2. 取得還原金鑰：使用者設定新裝置時，向憑證管理工具要求還原金鑰。使用者不需額外輸入資訊即可登入。
   3. 處理憑證擷取回應：將還原金鑰從用戶端應用程式傳送至應用程式伺服器，以便登入使用者。
3. 刪除還原金鑰。

建立還原金鑰

使用者向應用程式完成驗證後，請立即建立還原金鑰 (登入後或後續啟動應用程式時，如果使用者已登入)。

注意： 還原金鑰會與應用程式的專屬套件名稱綁定。如果貴機構的主要應用程式和子應用程式有不同的套件名稱，請為每個應用程式建立個別的還原金鑰。

例項化 Credential Manager

使用應用程式的活動內容，例項化 CredentialManager 物件。

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

從應用程式伺服器取得憑證建立選項

在應用程式伺服器中使用符合 FIDO 標準的程式庫，將建立還原憑證所需的資訊傳送給用戶端應用程式，例如使用者、應用程式和額外設定屬性的相關資訊。如要進一步瞭解伺服器端導入作業，請參閱伺服器端指南。

建立還原金鑰

剖析伺服器傳送的公開金鑰建立選項後，請將這些選項包裝在 CreateRestoreCredentialRequest 物件中，並使用 CredentialManager 物件呼叫 createCredential() 方法，藉此建立還原金鑰。

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

程式碼重點

• CreateRestoreCredentialRequest 物件包含下列欄位：

  • requestJson：應用程式伺服器以 Web Authentication API 格式傳送的憑證建立選項，適用於 PublicKeyCredentialCreationOptionsJSON。

  • isCloudBackupEnabled：Boolean 欄位，判斷是否應將還原金鑰備份到雲端。這項標記的預設值為 true。這個欄位的值如下：

    • true：(建議) 如果使用者已啟用 Google 備份和端對端加密功能 (例如螢幕鎖定)，這個值可將還原金鑰備份到雲端。
    • false：這個值會將金鑰儲存在本機，而非雲端。 如果使用者選擇從雲端還原，新裝置就無法使用金鑰。
  注意： 建議將 isCloudBackupEnabled 設為 true。如果雲端備份已停用，且使用者從雲端備份還原，系統會無法擷取還原金鑰。如果使用者透過雲端備份還原應用程式，將不會收到還原金鑰，也不會自動登入。

處理憑證建立回應

Credential Manager API 會傳回 CreateRestoreCredentialResponse 類型的回應。這個回應會以 JSON 格式保存公開金鑰憑證註冊回應。

將應用程式的公開金鑰傳送至信賴方伺服器。這個公開金鑰與您建立密碼金鑰時產生的公開金鑰類似。伺服器上處理密碼金鑰建立作業的程式碼，也可以處理還原金鑰建立作業。如要進一步瞭解伺服器端實作方式，請參閱密碼金鑰指南。

在還原金鑰建立程序中，請處理下列例外狀況：

• CreateRestoreCredentialDomException：如果 requestJson 無效，且不符合 PublicKeyCredentialCreationOptionsJSON 的 WebAuthn 格式，就會發生這個例外狀況。
• E2eeUnavailableException：如果 isCloudBackupEnabled 為 true，但使用者裝置未啟用資料備份或端對端加密功能 (例如螢幕鎖定)，就會發生這項例外狀況。
• IllegalArgumentException：如果 createRestoreRequest 為空或不是有效的 JSON，或者沒有符合 WebAuthn 規格的有效 user.id，就會發生這項例外狀況。

使用還原金鑰登入

在裝置設定程序中，使用「還原憑證」以無聲方式登入使用者。

從應用程式伺服器取得憑證擷取選項

將從伺服器取得還原金鑰所需的選項傳送至用戶端應用程式。 如需類似的密碼金鑰指引，請參閱「使用密碼金鑰登入」。如要進一步瞭解伺服器端實作方式，請參閱伺服器端驗證指南。

取得還原金鑰

如要在新裝置上取得還原金鑰，請呼叫 CredentialManager 物件的 getCredential() 方法。

在下列情況中，您可以擷取還原金鑰：

• (建議) 應用程式資料還原後立即執行。使用 BackupAgent 設定應用程式的備份作業，並在 onRestore 回呼中完成 getCredential 功能，確保應用程式的憑證會在應用程式資料還原後立即還原。這樣一來，使用者首次開啟新裝置時就不會遇到延遲問題，而且不必等待開啟應用程式，就能與裝置互動。
• 首次在裝置上啟動應用程式時。

如要在使用者於新裝置上首次開啟應用程式前傳送通知，請在 BackupAgent 的 onRestore 回呼中擷取還原金鑰。這對訊息或通訊應用程式尤其重要。

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

憑證管理工具 API 會傳回 GetCredentialResponse 類型的回應。這個回應會保留公開金鑰。

處理登入回應

將應用程式中的公開金鑰傳送至信賴方伺服器，即可用來登入使用者。在伺服器端，這項動作與使用密碼金鑰登入類似。伺服器上處理密碼金鑰登入作業的程式碼，同樣也能處理還原金鑰登入作業。如要進一步瞭解密碼金鑰的伺服器端實作方式，請參閱「使用密碼金鑰登入帳戶」。

注意： 雖然還原金鑰和密碼金鑰使用相同的基礎伺服器實作方式，但在應用程式伺服器的資料庫中儲存這些金鑰時，請加以區別。如果設有密碼金鑰管理頁面，這項區別就非常重要，因為使用者可以直接管理自行建立的密碼金鑰，而還原金鑰則由系統管理，不會顯示在密碼金鑰管理頁面。

刪除還原金鑰

憑證管理工具沒有狀態，也不會感知使用者活動，因此不會在還原金鑰使用完畢後自動刪除。如要刪除還原金鑰，請呼叫 clearCredentialState() 方法。為確保安全性，請在使用者登出時刪除金鑰。這樣一來，使用者下次在同一部裝置上開啟應用程式時，系統就會將使用者登出，並提示重新登入。

系統會將解除安裝應用程式解讀為要從該裝置刪除對應的還原金鑰，與使用者登出時的意圖類似。

只有在下列情況下，系統才會移除還原金鑰：

• 系統層級動作：使用者解除安裝應用程式或清除應用程式資料。
• 應用程式層級呼叫：在應用程式程式碼中處理使用者登出時，呼叫 clearCredentialState()，以程式輔助方式刪除金鑰。

使用者登出應用程式時，請呼叫 CredentialManager 物件的 clearCredentialState() 方法。

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)