共用方式為

適用於 Windows 應用程式的認證保險箱

  • 發行項

本文說明 Windows 應用程式如何使用「認證保險箱」安全地儲存和擷取使用者認證，並在具有使用者 Microsoft 帳戶的裝置之間漫遊。

認證保險箱存取的 Windows 執行階段 （WinRT） API 是 Windows 軟體開發工具包 （SDK） 的一部分。 這些 API 已建立以用於 通用 Windows 平台 （UWP） 應用程式，但它們也可以在 WinUI 應用程式或封裝的桌面應用程式中使用，包括 WPF 和 Windows Forms。 如需在 Windows 傳統型應用程式中使用 WinRT API 的詳細資訊，請參閱在傳統型應用程式中呼叫 Windows 執行階段 API。

範例案例概觀

例如，您有一個應用程式連接到服務以存取受保護的資源 (例如媒體檔案或社交網路)。 您的服務需要每個使用者的登入資訊。 您已在應用程式中內建UI，以取得使用者的使用者名稱和密碼，然後用來將使用者登入服務。 使用 Credential Locker API，您可以儲存使用者的使用者名和密碼，並輕鬆檢索它們，並在使用者下次打開您的應用程式時自動登入使用者，無論他們使用什麼裝置。

儲存在認證保險箱中的使用者認證不會過期、不會受到ApplicationData.RoamingStorageQuota的影響，也不會因為傳統漫遊數據等無活動而清除。 不過，您只能在認證保險箱中儲存每個應用程式最多 20 個認證。

認證保險箱對於網域帳戶的運作方式稍有不同。 如果您的 Microsoft 帳戶儲存了憑證，並且您將該帳戶與網域帳戶 (例如您在工作中使用的帳戶) 關聯，則您的憑證將漫遊到該網域帳戶。 但是，使用網域帳戶登入時新增的任何新憑證都不會漫遊。 這可確保網域的私人認證不會在網域外部公開。

儲存使用者憑證

  1. 使用 Windows.Security.Credentials 命名空間中的 PasswordVault 物件取得憑證鎖的參考。
  2. 建立一個包含應用程式識別碼、使用者名稱和密碼的PasswordCredential 對象，並將其傳遞給 PasswordVault.Add 方法以將憑證新增至儲物櫃。
var vault = new Windows.Security.Credentials.PasswordVault();
vault.Add(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

擷取使用者認證

當您有 PasswordVault 對象的參考 之後，您有數個選項可從 Credential Locker 擷取使用者認證。

讓我們來看看一個範例，其中我們將資源名稱全域儲存在應用程式中，如果找到使用者的憑證，我們會自動登入使用者。 如果我們發現同一使用者有多個憑證，我們會要求使用者選擇登入時使用的預設憑證。

private string resourceName = "My App";
private string defaultUserName;

private void Login()
{
    var loginCredential = GetCredentialFromLocker();

    if (loginCredential != null)
    {
        // There is a credential stored in the locker.
        // Populate the Password property of the credential
        // for automatic login.
        loginCredential.RetrievePassword();
    }
    else
    {
        // There is no credential stored in the locker.
        // Display UI to get user credentials.
        loginCredential = GetLoginCredentialUI();
    }

    // Log the user in.
    ServerLogin(loginCredential.UserName, loginCredential.Password);
}

private Windows.Security.Credentials.PasswordCredential GetCredentialFromLocker()
{
    Windows.Security.Credentials.PasswordCredential credential = null;

    var vault = new Windows.Security.Credentials.PasswordVault();

    IReadOnlyList<PasswordCredential> credentialList = null;

    try
    {
        credentialList = vault.FindAllByResource(resourceName);
    }
    catch(Exception)
    {
        return null;
    }

    if (credentialList.Count > 0)
    {
        if (credentialList.Count == 1)
        {
            credential = credentialList[0];
        }
        else
        {
            // When there are multiple usernames,
            // retrieve the default username. If one doesn't
            // exist, then display UI to have the user select
            // a default username.
            defaultUserName = GetDefaultUserNameUI();

            credential = vault.Retrieve(resourceName, defaultUserName);
        }
    }

    return credential;
}

刪除使用者憑證

刪除憑證儲物櫃中的使用者憑證也是一個快速的兩步驟過程。

  1. 使用 Windows.Security.Credentials 命名空間中的 PasswordVault 物件取得憑證鎖的參考。
  2. 將您想要刪除的認證傳遞至 PasswordVault.Remove 方法。
var vault = new Windows.Security.Credentials.PasswordVault();
vault.Remove(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

最佳作法

僅將憑證鎖用於密碼，而不是用於較大的資料 blob。

只有在滿足以下條件時，才將密碼保存在憑證儲物櫃中：

  • 使用者已成功登入。
  • 使用者已選擇儲存密碼。

切勿使用應用程式資料或漫遊設定以純文字形式儲存憑證。

相關內容