適用於 Go 的 Azure 身分識別連結庫中的認證鏈結

Azure 身分識別程式庫提供 認證資訊—實作 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}
    credential, 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 開發人員命令列介面	如果開發人員使用 Azure Developer CLI 的 `azd auth login` 命令向 Azure 進行驗證，請使用該帳戶進行驗證。
6	Azure PowerShell	如果開發人員使用 Azure PowerShell 的 `Connect-AzAccount` Cmdlet 向 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
}

如何自訂 DefaultAzureCredential

下列各節說明控制鏈結中包含哪些認證的策略。

排除認證類型類別

若要排除所有 Developer tool 或 Deployed service 認證，請將環境變數 AZURE_TOKEN_CREDENTIALS 分別設定為 prod 或 dev。使用prod值時，基礎憑證鏈如下所示：

顯示 DefaultAzureCredential 且AZURE_TOKEN_CREDENTIALS設定為『prod』的圖表。

使用的值 dev 時，鏈結看起來如下：

顯示 DefaultAzureCredential 且AZURE_TOKEN_CREDENTIALS設定為 'dev' 的圖表。

這很重要

模組 AZURE_TOKEN_CREDENTIALS 1.10.0 版和更新版本支援 azidentity 環境變數。

若要確保已定義環境變數，請將選項 RequireAzureTokenCredentials 設定為 true：

opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true}
credential, err := azidentity.NewDefaultAzureCredential(&opts)
if err != nil {
    // TODO: handle error
}

使用特定認證

若要排除除了一個認證以外的所有認證，請將環境變數 AZURE_TOKEN_CREDENTIALS 設定為認證名稱。例如，您可以將設定為，以減少的DefaultAzureCredential鏈結AzureCLICredential。AZURE_TOKEN_CREDENTIALSAzureCLICredential 字串比較是以不區分大小寫的方式執行。環境變數的有效字串值包括：

AzureCLICredential
AzureDeveloperCLICredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
WorkloadIdentityCredential

這很重要

環境變數 AZURE_TOKEN_CREDENTIALS 支援模組 1.11.0 版和更新版本中的個別認證名稱 azidentity 。

若要確保已定義環境變數，請將選項 RequireAzureTokenCredentials 設定為 true：

opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true}
credential, err := azidentity.NewDefaultAzureCredential(&opts)
if err != nil {
    // TODO: handle error
}

ChainedTokenCredential 概觀

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

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

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

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

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

圖表，顯示由 Azure CLI 和 Azure 開發人員 CLI 認證所組成的 ChainedTokenCredential 實例驗證流程。

提示

為了提升效能，請優化 ChainedTokenCredential 中的認證排序，按照從最常使用到最少使用的順序排列。

DefaultAzureCredential 的使用指引

DefaultAzureCredential 無疑是開始使用 Azure 身分識別庫的最簡單方式，但這種便利性伴隨著一些取捨。將應用程式部署至 Azure 之後，您應該瞭解應用程式的驗證需求。因此，請將 DefaultAzureCredential 取代為特定的 TokenCredential 實作，例如 ManagedIdentityCredential。

原因如下：

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

除錯鏈式憑證

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

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)

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-03