Microsoft Entra 與 Microsoft 的認證。Data.SqlClient

適用於： .NET Framework .NET .NET 標準

使用 Microsoft Entra ID 連接，且不需在應用程式中儲存 SQL 密碼。選擇應用程式運行的主機登入方式，將該身份配置到目標資料庫，並保持傳輸層安全（TLS）憑證驗證啟用。

概觀

驅動程式提供的 Active Directory ... 認證模式同時需要 Microsoft.Data.SqlClient 和 Microsoft.Data.SqlClient.Extensions.Azure。安裝匹配版本：

dotnet add package Microsoft.Data.SqlClient --version 7.1.0
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.0

該擴充功能會自動註冊其提供者。提供自家 AccessToken、或 AccessTokenCallback認證提供者的應用程式，並不需要 Azure 擴充功能來達成這個目的。加入你自己代幣代碼使用的身份庫。

連線前：

為 Azure SQL 設定 Microsoft Entra 認證，或依照目標服務的等效設定。
授權應用程式或使用者身份存取目標資料庫。取得令牌並不代表資料庫權限。
允許網路存取端點，並明確選擇資料庫。
選擇支援的認證模式，並讓其憑證在應用程式主機上可用。

Microsoft Fabric 中的 SQL 資料庫僅支援 Microsoft Entra 認證。它不支援 SQL 認證或 SQL 登入。使用 Fabric 入口網站的連接字串來設定目標端點。

選擇驗證模式

設定 Authentication 為本表中的連接字串值之一。釋出欄幫助你從舊驅動程式遷移過來。目前的應用程式應該安裝概述中描述的套件。

連接字串值	使用	首次支援發行
`Active Directory Integrated`	透過在已設定的網域及 Microsoft Entra 環境中使用整合 Windows 認證（IWA）來取得憑證。	1.0 版本為 .NET 框架;2.0 版本則涵蓋支援目標。
`Active Directory Interactive`	支援多重驗證（MFA）的使用者登入。	1.0 版本為 .NET 框架;2.0 版本則涵蓋支援目標。
`Active Directory Service Principal`	應用程式的客戶端 ID 和客戶端秘密。	2.0.
`Active Directory Device Code Flow`	使用者可透過另一台裝置的瀏覽器登入。	2.1.
`Active Directory Managed Identity` 或 `Active Directory MSI`	系統指派或使用者指派的管理身份可供應用程式主機使用。	2.1.
`Active Directory Default`	透過 Azure Identity 憑證鏈發現可用的憑證。	3.0.
`Active Directory Workload Identity`	結合工作負載身份與投影令牌檔案。	5.2.
`Active Directory Password`	已棄用的使用者名稱/密碼流程。不要用來做新應用程式。	1.0.

Authentication=Sql Password是SQL認證，不是Microsoft Entra認證。請參見 SQL Server 與 Windows Authentication。

開啟連線

對於 .NET 主控台應用程式，替換佔位符後，請設定SQL_CONNECTION_STRING為本文中相應的範本。此範例開啟連線並列印資料庫名稱：

using Microsoft.Data.SqlClient;

string connectionString = Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException("Set SQL_CONNECTION_STRING before running.");

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());

每種模式都有不同的主機條件。解析器接受的連接字串並不代表主機能取得權杖，或身份能存取資料庫。

使用整合驗證

Active Directory Integrated利用登入的網域身份取得 Microsoft Entra 令牌。它需要適當的聯合或聯邦身份設定。它和直接使用 SQL Server 的 Windows Authentication 不同Integrated Security=true。

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Integrated;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

不要提供密碼或 SqlCredential。在現代 .NET 中，使用者名稱提示是可選的;.NET Framework 不接受此模式的使用者名稱。 IWA 無法滿足互動式 MFA 挑戰。當租戶需要使用者互動時，請使用互動式認證。

使用互動式驗證

用於 Active Directory Interactive 登入桌面或開發者應用程式的人。認證提供者會提示使用者，並支援多重身份驗證（MFA）。可選 User ID=<user_id> 的是一個登入提示，而不是密碼。

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

不要提供 Password 或 SqlCredential。不要在無人值守服務中使用互動模式。

使用服務主體驗證

內建模式使用 Active Directory Service Principal 應用程式的客戶端 ID 為 User ID ，客戶端秘密為 Password。在資料庫中配置服務主體，並只授予它所需的權限。

從受保護的設定中取得秘密，而不是嵌入原始碼。此主控台範例讀取注入進程的值：

using Microsoft.Data.SqlClient;

static string Required(string name) =>
    Environment.GetEnvironmentVariable(name)
    ?? throw new InvalidOperationException($"Set {name} before running.");

var options = new SqlConnectionStringBuilder
{
    DataSource = Required("SQL_SERVER"),
    InitialCatalog = Required("SQL_DATABASE"),
    Authentication = SqlAuthenticationMethod.ActiveDirectoryServicePrincipal,
    UserID = Required("AZURE_CLIENT_ID"),
    Password = Required("AZURE_CLIENT_SECRET"),
    Encrypt = SqlConnectionEncryptOption.Mandatory,
    TrustServerCertificate = false,
    MultiSubnetFailover = true
};

using var connection = new SqlConnection(options.ConnectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());

設定 SQL_SERVER 為你的傳輸控制協定（TCP）端點，例如 tcp:contoso.database.windows.net,1433，並 SQL_DATABASE 設定為資料庫名稱。不要記錄環境值或連接字串。

對於基於憑證的應用程式憑證，請透過 AccessTokenCallback 取得令ClientCertificateCredential牌。對於聯邦憑證，請使用工作負載身份或適當的令牌回調。連接字串服務主模式本身需要一個用戶端秘密。

使用裝置程式碼流程驗證

當應用程式主機沒有瀏覽器，但使用者可以在其他裝置登入時，請使用此模式。請依照驗證流程提供的驗證網址和代碼操作。

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Device Code Flow;Connect Timeout=180;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Connect Timeout 界限認證;此範例允許180秒。不要提供 User ID， Password或 SqlCredential。裝置程式碼流程仍需人員協助，且不適合無人值守服務。

使用受控識別驗證

對於 Azure 託管的應用程式，當主機支援時，請使用受管理身份。該身份屬於應用程式主機，而非自動屬於資料庫伺服器。

系統指派的管理身份共享主機資源的生命週期。
使用者指派的管理身份是一個獨立資源，你可以指派給支援的主機。

對於系統指派的身份，省略：User ID

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

對於使用者指派的身份，請提供其 用戶端 ID：

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;User ID=<client_id>;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Active Directory MSI 是同一模式的相容拼法。不要提供密碼或 SqlCredential。主機必須公開所選的管理身份，且該身份必須具備資料庫存取權限。開發者工作站不會因為使用這個連接字串而獲得受管理身份。

從 SqlClient 2.1 遷移時，請將使用者指派身份的 物件 ID 替換為其 用戶端 ID。 SqlClient 使用 3.0 起的客戶端 ID。

使用預設驗證

Active Directory Default使用 Azure 身份憑證鏈來發現可用的身份：

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

候選者取決於已安裝的 Azure Identity 版本與設定。它們包括環境憑證、工作負載身份、管理身份，以及登入開發工具，如 Visual Studio、Azure Command-Line 介面（CLI）、Azure PowerShell 和 Azure 開發者 CLI。請參閱 DefaultAzureCredential 以了解目前的鏈條。

SqlClient 在此模式下會 InteractiveBrowserCredential 被停用。選擇 Active Directory Interactive 應用程式本身是否需要提示登入。開發工具的憑證可以使用先前互動式登入所建立的會話。

這很重要

Active Directory Default 可能會讓第一個連線變慢，因為 DefaultAzureCredential 會依序嘗試憑證提供者，直到有一個提供令牌。無法接通的提供者可能會在工作提供者抵達前，造成發現、網路或程序啟動延遲。在生產環境中偏好特定的認證模式，例如 Active Directory Managed Identity、 Active Directory Workload Identity或 Active Directory Service Principal，以避免這種發現的開銷。憑證與令牌快取可以減少後續的取得工作;不要假設每個合併的連線都會重複整個鏈條。

當主機配置變更時 Active Directory Default，所選身份會改變。

對於較舊的部署，該鏈內的工作負載身份與 Azure Developer CLI 支援是在 SqlClient 5.1.4 中實現的。這個功能與 5.2 版本推出的專用 Active Directory Workload Identity 模式不同。 Azure PowerShell 支援於 5.0 版本中出現。

使用工作負載身份驗證

用於 Active Directory Workload Identity 設定為聯邦工作負載身份的主機。身份提供者必須信任被投射代幣的發行者與主體。

證件內容如下：

AZURE_TENANT_ID：租戶身分證。
AZURE_CLIENT_ID：應用程式或使用者指定的管理身份用戶端識別碼。
AZURE_FEDERATED_TOKEN_FILE：是投影令牌檔案的路徑。

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Workload Identity;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

一個可選 User ID=<client_id> 的選項會覆蓋用戶端 ID。連接字串不會覆蓋租戶 ID 或 token-file 路徑。不要把 token 檔案的內容放進連接字串或 logs。

替換已棄用的密碼驗證

這很重要

ActiveDirectoryPassword 驗證選項（Microsoft Entra ID 密碼驗證）在 Microsoft SQL 驅動程式中已被棄用。這種高風險的認證流程與強制的 Microsoft Entra 多重驗證（MFA）不相容，且在強制執行多重驗證的租戶中可能無法運作。計劃遷移到不同的 Microsoft Entra 認證方式。

Microsoft Entra ID 的密碼驗證基於 OAuth 2.0 資源擁有者密碼憑證（ROPC）授權，允許應用程式直接處理使用者的密碼來登入。

Microsoft 建議不要使用 ROPC 流程，因為它與多重認證（MFA）不相容。在大部分情況下，有更安全的替代方案可供使用，並建議使用。這種流程需要對應用程式高度信任，且存在其他流程中不存在的風險。只有在無法用更安全的流程時才使用這個流程。 Microsoft 正逐步放棄這種高風險的認證流程，以保護使用者免受惡意攻擊。欲了解更多資訊，請參閱 Azure 強制多重驗證的規劃。

當使用者在登入時，請使用 ActiveDirectoryInteractive 或 ActiveDirectoryIntegrated 認證，使登入使用者的稽核憑證及條件存取政策得以適用。

對於服務對服務的無人值守情境，請遵循 Microsoft Entra 服務帳戶指導方針：

如果你的應用程式是在 Azure 基礎設施上執行，請使用 ActiveDirectoryMSI（或某些驅動程式中的 ActiveDirectoryManagedIdentity）。受管理身份消除了維護與輪替秘密與憑證的負擔。
如果無法使用受管理身份（例如應用程式在 Azure 外執行），則使用 ActiveDirectoryServicePrincipal。在驅動程式支援時，偏好使用用戶端憑證而非用戶端秘密。使用憑證時，私鑰會留在用戶端，只有簽署的斷言會送給 Microsoft Entra 以驗證客戶端。如果金鑰儲存在硬體（如 TPM 或 HSM）或標記為不可匯出，就無法像用戶端秘密那樣以字串形式複製。
不要把 Microsoft Entra 使用者帳號當作服務帳號使用。

Active Directory Password 使用資源擁有者密碼憑證流程，無法滿足多重身份驗證（MFA）要求。對應 SqlAuthenticationMethod.ActiveDirectoryPassword 的枚舉成員已過時。使用者可選擇互動式認證，或服務可選擇管理身份、工作負載身份或應用程式憑證。

自訂 Microsoft Entra 認證

請從以下應用程式介面（API）中選擇符合您需求的最小自訂化：

需求	API
提供已取得的代幣。	`SqlConnection.AccessToken`。
使用應用程式選擇的憑證取得並更新代幣。	`SqlConnection.AccessTokenCallback`。
可自訂裝置代碼呈現或互動式登入。	`ActiveDirectoryAuthenticationProvider`來自 Azure 擴充套件。
實作駕駛認證提供者。	從提供者中推導 `SqlAuthenticationProvider` 並註冊。

透過自訂 ActiveDirectoryAuthenticationProvider，你可以提供應用程式客戶端 ID、設定裝置代碼或授權碼回調，並在支援時設定互動式登入的父視窗。使用已安裝擴充套件的 provider API 參考來簽名。

直接提供存取憑證

在打開連接前設定好 SqlConnection.AccessToken 。核心驅動程式支援此特性，無需 Azure 擴充功能。

字面的 token 是 connection-pool 金鑰的一部分。不同的代幣會產生不同的池。 SqlClient 不會透過這個屬性收到有效期限，也無法幫你續約權杖。取得有效的新連線權杖，並在代幣到期時清除受影響的池，尤其是當你設定非零 Min Pool Size時。

不要與 Authentication、 AccessTokenCallbackSspiContextProviderUser IDSqlCredentialPassword或結合。AccessToken 千萬不要記錄代幣。

使用 AccessTokenCallback

建議 AccessTokenCallback 你的應用程式自行取得代幣並使用連線池。回調會回傳一個憑證及其到期時間，讓 SqlClient 可以申請續期以進行合併認證。 API 從 SqlClient 5.2 開始提供。

重複使用同一個代理實例和憑證物件，來處理應該共用池的連線。回撥代表是池中鑰匙的一部分。為每個連線建立新的閉合，可以為每個連線建立獨立的池。

這很重要

回傳相同的安全上下文，針對相同的回調輸入。不要在共享回調中從環境請求狀態中選擇不同的使用者。否則，合併連線可能會以錯誤身份回傳。

這個 .NET 控制台範例使用已登入的 Azure CLI 身份來進行本地開發。安裝 Microsoft.Data.SqlClient 和 Azure.Identity，使用 Azure CLI 登入，SQL_SERVER並設定和 SQL_DATABASE。這個範例不需要 Azure 擴充功能。

using Azure.Core;
using Azure.Identity;
using Microsoft.Data.SqlClient;

internal static class Program
{
    private static readonly TokenCredential Credential = new AzureCliCredential();

    private static readonly Func<SqlAuthenticationParameters, CancellationToken,
        Task<SqlAuthenticationToken>> TokenCallback = async (parameters, cancellationToken) =>
    {
        string scope = parameters.Resource.EndsWith("/.default", StringComparison.Ordinal)
            ? parameters.Resource
            : parameters.Resource + "/.default";
        AccessToken token = await Credential.GetTokenAsync(
            new TokenRequestContext(new[] { scope }), cancellationToken);
        return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
    };

    private static async Task Main()
    {
        var options = new SqlConnectionStringBuilder
        {
            DataSource = Required("SQL_SERVER"),
            InitialCatalog = Required("SQL_DATABASE"),
            Encrypt = SqlConnectionEncryptOption.Mandatory,
            TrustServerCertificate = false,
            MultiSubnetFailover = true
        };

        using var connection = new SqlConnection(options.ConnectionString)
        {
            AccessTokenCallback = TokenCallback
        };
        await connection.OpenAsync();
        using var command = new SqlCommand("SELECT DB_NAME();", connection);
        Console.WriteLine(await command.ExecuteScalarAsync());
    }

    private static string Required(string name) =>
        Environment.GetEnvironmentVariable(name)
        ?? throw new InvalidOperationException($"Set {name} before running.");
}

對於生產環境，請將預定憑證（如 ManagedIdentityCredential、 WorkloadIdentityCredential、或 ClientCertificateCredential）替換AzureCliCredential，並設定其前置條件。在共用回撥的連線尚未可用時，不要更改其身份。

不要與 Authentication、整合安全、AccessToken或 SspiContextProvider合併AccessTokenCallback。回調可以作為身份選擇器， User ID 但你的回調必須一致地解讀它。這個例子沒有使用選擇器，因為它只有一個固定的憑證。

支援自訂的 SQL 驗證提供者

從衍生 SqlAuthenticationProvider出，實作其令牌取得合約，並註冊 SqlAuthenticationProvider.SetProvider 為你所替換的認證方法。在應用程式初始化時，先登錄提供者，然後再開啟連線。

提供者必須回傳有效的憑證及有效期限，該資源與權限。與回調相同的安全上下文規則也適用於提供者。覆蓋提供者不會移除目標服務的身份、租戶或資料庫權限要求。

遷移至 Microsoft.Data.SqlClient 7.0

跨套件區段升級的應用程式應檢視相依性與認證設定。

7.0 改變了什麼

核心驅動程式不再引入 Azure 和 Microsoft Entra 的認證依賴。內建 ActiveDirectoryAuthenticationProvider 的合約會移動到 Microsoft.Data.SqlClient.Extensions.Azure，且共享合約在 Microsoft.Data.SqlClient.Extensions.Abstractions。

步驟 1：安裝 Azure 擴充套件

對於驅動程式提供的 Microsoft Entra 模式，請安裝與 Azure 擴充功能相符的版本，如概述所示。隨應用程式部署擴充功能。內建模式無需手動註冊醫療提供者。

步驟 2：替換已棄用的認證模式

換 Active Directory Password 成適合你應用程式使用者互動與主機模式的模式。對於無人值守部署，請選擇特定的工作負載身份，而非依賴開發者的登入。

步驟三：檢視連接串

如果現有支援 Authentication 值仍符合部署需求，就保留它。確認資料庫名稱、身份選擇器、加密設定及網路存取權限。不要加到Integrated Security=trueMicrosoft Entra 連接字串。

不使用 Entra ID 認證的應用程式

SQL 密碼和 Windows 整合認證不需要 Azure 擴充功能。已取得自身代幣的應用程式，仍可繼續使用 AccessToken 核心驅動程式及 AccessTokenCallback 所選身份庫。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-29

Microsoft Entra 與 Microsoft 的認證。Data.SqlClient

概觀

選擇驗證模式

開啟連線

使用整合驗證

使用互動式驗證

使用服務主體驗證

使用裝置程式碼流程驗證

使用受控識別驗證

使用預設驗證

使用工作負載身份驗證

替換已棄用的密碼驗證

自訂 Microsoft Entra 認證

直接提供存取憑證

使用 AccessTokenCallback

支援自訂的 SQL 驗證提供者

遷移至 Microsoft.Data.SqlClient 7.0

7.0 改變了什麼

步驟 1：安裝 Azure 擴充套件

步驟 2：替換已棄用的認證模式

步驟三：檢視連接串

不使用 Entra ID 認證的應用程式

相關內容

意見反應

其他資源