適用於 Go 的 Azure 身分識別用戶端程式庫中的憑證鏈條

發行項
12/16/2024

Azure Identity 用戶端程式庫提供認證—實作 Azure Core 程式庫的 TokenCredential 介面的公開類型。憑證代表從 Microsoft Entra ID 取得存取令牌的不同驗證流程。這些憑證可以串聯在一起，以形成一個按順序嘗試的認證機制序列。

鏈結認證的運作方式

在運行時間，認證鏈結會嘗試使用序列的第一個認證進行驗證。如果該認證無法取得存取令牌，則會嘗試序列中的下一個認證，依此方式，直到成功取得存取令牌為止。下列順序圖說明此行為：

顯示認證鏈結順序的圖表。

為何使用認證鏈結

鏈結認證可以提供下列優點：

環境感知：根據應用程式執行所在的環境自動選取最適當的認證。如果沒有它，您必須撰寫如下的程式代碼：

// Set up credential based on environment (Azure or local development)
if os.Getenv("WEBSITE_HOSTNAME") != "" {
    clientID := azidentity.ClientID("abcd1234-...")
    opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
    cred, err := azidentity.NewManagedIdentityCredential(&opts)

    if err != nil {
      // TODO: handle error
    }
}
else {
    // Use Azure CLI Credential
    credential, err = azidentity.NewAzureCLICredential(nil)

    if err != nil {
      // TODO: handle error
    }
}

無縫轉換：您的應用程式可以在不變更驗證碼的情況下，從本機開發移至預備或生產環境。
增強的彈性：包含一種後備機制，當先前的認證憑證無法取得存取令牌時，會移至下一個憑證。

如何選擇鏈結認證

使用 Go 時，認證鏈結有兩個選項：

使用預先設定的鏈結：使用由 DefaultAzureCredential 類型實作的預先設定鏈結。如需此方法，請參閱 DefaultAzureCredential 概觀一節。
建置自定義憑證鏈：從空白鏈結開始，並僅包含您所需的內容。如需此方法，請參閱 ChainedTokenCredential 概觀一節。

DefaultAzureCredential 概觀

DefaultAzureCredential 是基於特定概念預先設定的一系列認證。其設計目的是支援許多環境，以及最常見的驗證流程和開發人員工具。在圖形化形式中，基礎鏈結看起來像這樣：

DefaultAzureCredential 嘗試認證的順序如下。

次序	憑據	描述
1	環境	讀取環境變數的集合，以判斷應用程式服務主體（應用程式使用者）是否已為應用程式設定。如果是，`DefaultAzureCredential` 使用這些值向 Azure 驗證應用程式。此方法最常用於伺服器環境，但也可以在本機開發時使用。
2	工作負載身分識別	如果應用程式部署至已啟用工作負載識別的 Azure 主機，請驗證該帳戶。
3	受控識別	如果應用程式部署至已啟用受控識別的 Azure 主機，請使用該受控識別向 Azure 驗證應用程式。
4	Azure 命令列介面 (CLI)	如果開發人員使用 Azure CLI 的 `az login` 命令向 Azure 進行驗證，請使用相同的帳戶向 Azure 驗證應用程式。
5	Azure Developer CLI	如果開發人員使用 Azure Developer CLI 的 `azd auth login` 命令向 Azure 進行驗證，請使用該帳戶進行驗證。

最簡單的形式，您可以使用無參數版本的 DefaultAzureCredential，如下所示：

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    )

// create a credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // TODO: handle error
}

// create a Blob service client 
accountURL := "https://<my_account_name>.blob.core.windows.net"
client, err := azblob.NewClient(accountURL, credential, nil)
if err != nil {
    // TODO: handle error
}

ChainedTokenCredential 概觀

ChainedTokenCredential 是一個空鏈結，可供您新增認證以符合應用程式需求。例如：

managed, err := azidentity.NewManagedIdentityCredential(nil)
if err != nil {
  // handle error
}

azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}

chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{managed, azCLI}, nil)
if err != nil {
  // handle error
}

上述程式代碼範例會建立由兩個認證組成的量身訂做認證鏈結。先嘗試 ManagedIdentityCredential，然後視需要 AzureCliCredential。在圖形形式中，鏈條看起來像這樣：

顯示由受控識別認證和 Azure CLI 認證所組成的 ChainedTokenCredential 實例驗證流程的圖表。

提示

為了提升效能，請在生產環境的 ChainedTokenCredential 中優化認證順序。用於本機開發環境的認證應該是最後新增的。

DefaultAzureCredential 的使用指引

DefaultAzureCredential 無疑是開始使用 Azure 身分識別用戶端程式庫的最簡單方式，但這種便利性也意味著需要作出一些取捨。將應用程式部署至 Azure 之後，您應該瞭解應用程式的驗證需求。因此，強烈建議您考慮從 DefaultAzureCredential 移至下列其中一個解決方案：

特定認證實作，例如 ManagedIdentityCredential。
精簡的 ChainedTokenCredential 實作已針對您的應用程式運行的 Azure 環境進行優化。

原因如下：

偵錯挑戰：當驗證失敗時，偵錯和識別違規認證可能會很困難。您必須啟用記錄，才能查看從一個認證到下一個認證的進展，以及每個認證的成功/失敗狀態。如需詳細資訊，請參閱偵錯鏈結認證。
效能負擔問題：循序嘗試多個認證可能會導致效能負擔的問題。例如，在本地開發環境中運行時，受控識別無法使用。因此，ManagedIdentityCredential 在本機開發環境中總是會失敗，除非透過對應的 exclude前置屬性明確停用。
無法預測的行為：DefaultAzureCredential 會檢查特定環境變數是否存在。有人有可能在主電腦上的系統層級新增或修改這些環境變數。這些變更會在全域範圍內套用，因此會改變在該計算機上執行的任何應用程式中 DefaultAzureCredential 在運行時的行為。

偵錯鏈結的認證

若要診斷非預期的問題，或了解串接的憑證的作用，在您的應用程式中啟用記錄。選擇性地將記錄篩選為僅從 Azure 身分識別用戶端連結庫發出的那些事件。例如：

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})
// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

如需解決特定認證類型錯誤的指導，請參閱疑難解答指南。

共用方式為