搭配使用 Microsoft Entra ID 與 Microsoft ODBC 驅動程式

下載 ODBC 驅動程式

注意

雖然 Microsoft Entra ID 是 Azure Active Directory（Azure AD）的新名稱，但為了防止破壞現有的環境，Azure AD 仍會保留在某些硬式編碼元素中，例如 UI 字段、連線提供者、錯誤碼和 Cmdlet。 在本文中，這兩個名稱是可互換的。

目的

Microsoft ODBC Driver for SQL Server 13.1 版和更高版本可讓 ODBC 應用程式使用 Microsoft Entra ID 的身分識別，連線至 Azure SQL Database 或 Azure SQL 受控執行個體。 可以透過使用者名稱和密碼、Microsoft Entra 存取權杖、Microsoft Entra 受控識別 (17.3+) 或同盟已加入網域環境 (Linux/macOS 上的 17.6+) 中的整合式 Windows 驗證來完成驗證。 針對 ODBC Driver 13.1 版，Microsoft Entra 存取權杖驗證僅限 Windows。 ODBC Driver 17 版和更新版本支援跨所有平台 (Windows、Linux 及 macOS) 進行此驗證。 適用於 Windows 的 ODBC Driver 17.1 版中已引進支援多重要素驗證的新 Microsoft Entra 互動式驗證方法。 在 ODBC 驅動程式 17.3.1.1 版中，已針對系統指派與使用者指派的受控身分識別，新增新的 Microsoft Entra 受控識別驗證方法。 這些選項全部都是使用新的 DSN 和連接字串關鍵字，以及連線屬性來完成。

如需使用 Microsoft Entra 驗證，您必須設定 Azure SQL 資料來源。 如需詳細資訊，請參閱使用 Azure SQL 設定和管理 Microsoft Entra 驗證。

注意

17.6 版之前的 Linux 和 macOS 上的ODBC驅動程式，僅支援直接針對 Microsoft Entra ID 進行 Microsoft Entra 驗證。 如果在 Linux 或 macOS 用戶端使用 Microsoft Entra 使用者名稱/密碼，而您的 Microsoft Entra 組態需要用戶端驗證 Microsoft Entra 同盟服務端點，則驗證可能會失敗。 從 17.6 版的驅動程式起，已移除這個限制。

新的和/或已修改的 DSN 與連接字串關鍵字

使用 DSN 或連接字串連線以控制驗證模式時，可以使用 Authentication 關鍵字。 連接字串中設定的值會覆寫 DSN 中設定的值 (如已提供)。 Authentication 設定的「前置屬性值」 是從連接字串和 DSN 值計算而來的值。

名稱	值	預設值	描述
Authentication	(未設定)、(空字串)、SqlPassword、ActiveDirectoryPassword、ActiveDirectoryIntegrated、ActiveDirectoryInteractive、ActiveDirectoryMsi、ActiveDirectoryServicePrincipal	(未設定)	控制驗證模式。 值 描述 (未設定) 由其他關鍵字決定的驗證模式 (現有的舊版連線選項)。 (空字串) (僅限連接字串)。覆寫和取消設定在 DSN 中設定的 Authentication 值。 SqlPassword 利用使用者名稱與密碼直接向 SQL 進行驗證。 ActiveDirectoryPassword 使用使用者名稱和密碼透過 Microsoft Entra 身分識別進行驗證。 ActiveDirectoryIntegrated 僅限 Windows 與 Linux/Mac 17.6+ 驅動程式。 使用透過 Microsoft Entra ID 與整合式驗證同盟的 Windows 認證進行驗證。 ActiveDirectoryInteractive 「僅限 Windows 驅動程式」 。 使用互動式驗證，以 Microsoft Entra 身分識別進行驗證 ActiveDirectoryMsi 使用 Microsoft Entra ID 驗證受控識別 如果是使用者指派的身分識別，請將 UID 設定為 Azure App Service 或 Azure 容器執行個體的身分識別用戶端識別碼，如果是其他，請使用物件識別碼。 若為系統指派的身分識別，則不需要UID。 ActiveDirectoryServicePrincipal (17.7+)使用 Microsoft Entra 服務主體進行驗證。 UID 設定為服務主體的用戶端識別碼。 PWD 設定為用戶端密碼。
Encrypt	(未設定)、Yes/Mandatory(18.0+)、No/Optional(18.0+)、Strict(18.0+)	(請參閱描述)	控制連接的加密。 如果 Authentication 設定的前置屬性值在 DSN 或連接字串中不是 none，則預設值為 Yes。 18.0.1+ 版中的預設值也是 Yes。 否則預設為 No。 如果屬性 SQL_COPT_SS_AUTHENTICATION 會覆寫 Authentication 的前置屬性值，請在 DSN、連接字串或連線屬性中明確設定 Encryption 的值。 如果在 DSN 或連接字串中將值設定為 Yes，則 Encryption 的前置屬性值為 Yes。

新的和/或已修改的連線屬性

下列預先連線的連線屬性已引進或修改來支援 Microsoft Entra 驗證。 當連線屬性具有對應的連接字串或 DSN 關鍵字且已設定時，連線屬性就會取得高優先順序。

屬性	類型	值	預設值	描述
SQL_COPT_SS_AUTHENTICATION	SQL_IS_INTEGER		(未設定)	請參閱上方的 Authentication 關鍵字描述。 提供 SQL_AU_NONE 以明確覆寫 DSN 和/或連接字串中設定的 Authentication 值，而 SQL_AU_RESET 會取消設定該屬性 (如已設定)，讓 DSN 或連接字串值能夠取得高優先順序。
SQL_COPT_SS_ACCESS_TOKEN	SQL_IS_POINTER	指向 ACCESSTOKEN 的指標或 NULL	NULL	如果不是 Null，請指定要使用的 Microsoft Entra 存取權杖。 指定存取權杖，並同時指定 UID、PWD、Trusted_Connection 或 Authentication 連接字串關鍵字或其對等屬性，是錯誤的。 注意： ODBC Driver 13.1 版僅在 Windows 上支援此設定。
SQL_COPT_SS_ENCRYPT	SQL_IS_INTEGER	%	(請參閱描述)	控制連接的加密。 SQL_EN_OFF 和 SQL_EN_ON 會分別停用和啟用加密。 如果 Authentication 設定的前置屬性值不是 none 或已設定 SQL_COPT_SS_ACCESS_TOKEN，而且未在 DSN 或連接字串中指定 Encrypt，則預設值為 SQL_EN_ON。 否則預設為 SQL_EN_OFF。 如果已將 SQL_COPT_SS_AUTHENTICATION 連線屬性設定為不是 none，若尚未在 DSN 或連接字串中指定 SQL_COPT_SS_ENCRYPT，請明確地將 Encrypt 設定為所需的值。 這個屬性的有效值會控制是否將針對連線使用加密。
SQL_COPT_SS_OLDPWD	-	-	-	Microsoft Entra 識別符不支援，因為無法透過 ODBC 連線完成對 Microsoft Entra 主體的密碼變更。 SQL Server 驗證的密碼逾期已在 SQL Server 2005 中推出。 已新增 SQL_COPT_SS_OLDPWD 屬性，讓用戶端能夠同時提供舊的和新的密碼進行連線。 設定這個屬性之後，提供者將不會針對第一次連線或未來連線使用連線集區，因為連接字串將會包含現已變更的「舊密碼」。
SQL_COPT_SS_INTEGRATED_SECURITY	SQL_IS_INTEGER	SQL_IS_OFF/SQL_IS_ON	SQL_IS_OFF	「已淘汰」 ；請改用設定為 SQL_AU_AD_INTEGRATED 的 SQL_COPT_SS_AUTHENTICATION。 針對伺服器登入的存取驗證強制使用 Windows 驗證 (Linux 和 macOS 上的 Kerberos)。 使用 Windows 驗證時，驅動程式會忽略在 SQLConnect、SQLDriverConnect 或 SQLBrowseConnect 處理期間所提供的使用者識別碼和密碼值。

Microsoft Entra ID 的 UI 新增項目 (僅限 Windows 驅動程式)

驅動程式的 DSN 設定和連線 UI 已利用搭配 Microsoft Entra ID 使用驗證所需的額外選項來增強。

在 UI 中建立和編輯 DSN

使用驅動程式的設定 UI 來建立或編輯現有的 DSN 時，可以使用 Microsoft Entra 驗證選項：

Authentication=ActiveDirectoryIntegrated表示 Azure SQL 的 Microsoft Entra 整合式驗證

Authentication=ActiveDirectoryPassword表示 Azure SQL 的 Microsoft Entra 使用者名稱/密碼驗證

Authentication=ActiveDirectoryInteractive表示 Azure SQL 的 Microsoft Entra 互動式驗證

注意

自驅動程式 17.9 版起，互動式驗證行為已有所變更。 除非驅動程式快取有效的存取權杖，否則系統一律會提示使用者輸入認證。 這項變更可讓 Microsoft Entra 已加入裝置上的使用者避免略過提示，並在使用 ActiveDirectoryInteractive 驗證時，使用快取認證自動登入。

Authentication=SqlPassword 表示對 SQL Server 和 Azure SQL 進行使用者名稱/密碼驗證

Trusted_Connection=Yes 表示 Windows 舊版 SSPI 整合式驗證

Authentication=ActiveDirectoryMsi 表示Microsoft Entra 受控識別驗證。

Authentication=ActiveDirectoryServicePrincipal表示 Microsoft Entra 服務主體驗證

這七個選項分別對應至 Trusted_Connection=Yes (現有僅限舊版 Windows SSPI 的整合式驗證) 以及 Authentication= ActiveDirectoryIntegrated、SqlPassword、ActiveDirectoryPassword、ActiveDirectoryInteractive、ActiveDirectoryMsi 和 ActiveDirectoryServicePrincipal。

SQLDriverConnect 提示 (僅限 Windows 驅動程式)

當 SQLDriverConnect 要求完成連線所需之資訊時顯示的提示對話方塊，其中包含四個適用於 Microsoft Entra 驗證的新選項：

這些選項對應至上述 DSN 設定 UI 中相同的六個可用選項。

範例連接字串

1. SQL Server 驗證：舊版語法。 伺服器憑證不會經過驗證，而且只有在伺服器強制進行加密時，才會使用加密。 使用者名稱/密碼會在連接字串中傳遞。

   server=Server;database=Database;UID=UserName;PWD=<password>;Encrypt=no;TrustServerCertificate=yes;

2. SQL 驗證：新語法。 用戶端會要求加密 (Encrypt 的預設值是 true)，且無論加密設定為何 (除非將 TrustServerCertificate 設定為 true)，都會驗證伺服器憑證。 使用者名稱/密碼會在連接字串中傳遞。

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=SqlPassword;

3. (向 SQL Server 或 SQL IaaS) 使用 SSPI 的整合式 Windows 驗證 (Linux 和 macOS 上的 Kerberos)：目前的語法。 除非伺服器需要加密，否則不會驗證伺服器憑證。

   server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;

4. ( 「僅限 Windows 驅動程式」 )。使用 SSPI 的整合式 Windows 驗證 (如果目標資料庫位於 SQL Server 或 Azure VM SQL Server)：新語法。 用戶端會要求加密 (Encrypt 的預設值是 true)，且無論加密設定為何 (除非將 TrustServerCertificate 設定為 true)，都會驗證伺服器憑證。

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;

5. Microsoft Entra 使用者名稱/密碼驗證 (如果目標資料庫位於 Azure SQL Database 或 Azure SQL 受控執行個體)。 無論加密設定為何，都會驗證伺服器憑證 (除非將 TrustServerCertificate 設定為 true)。 使用者名稱/密碼會在連接字串中傳遞。

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (「僅限 Windows 與 Linux/macOS 17.6+ 驅動程式」。)使用 ADAL 或 Kerberos 的整合式 Windows 驗證，其需要針對 Microsoft Entra 的存取權杖兌換 Windows 帳戶認證 (假設目標資料庫位於 Azure SQL)。 無論加密設定為何，都會驗證伺服器憑證 (除非將 TrustServerCertificate 設定為 true)。 在 Linux/macOS 上，需要有適當的 Kerberos 票證可供使用。 如需詳細資訊，請參閱下列關於同盟帳戶和使用整合式驗證一節。

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;

7. (僅限 Windows 驅動程式。) Microsoft Entra 互動式驗證會使用 Microsoft Entra 多重要素驗證技術來設定連線。 在此模式中，藉由提供登入識別碼來觸發 Azure 驗證對話方塊，並允許使用者輸入進階驗證以完成連線。 使用者名稱會在連接字串中傳遞。

   server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;

   

8. Microsoft Entra 受控識別驗證會使用系統指派或使用者指派的受控識別。 如果是使用者指派的身分識別，請將 UID 設定為 Azure App Service 或 Azure 容器執行個體的身分識別用戶端識別碼，如果是其他，請使用物件識別碼。 若為系統指派的身分識別，則不需要UID。
   

   針對系統指派的身分識別：

   server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;

   對於物件識別碼等於 myObjectId 之使用者指派的身分識別：

   server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;

9. Microsoft Entra 服務主體驗證

server=Server;database=Database;UID=clientId;PWD=<password>;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

備註

• 搭配 17.4.2 版以前的 Windows ODBC 驅動程式使用新的 Microsoft Entra 選項時，確認已安裝 SQL Server 的 Active Directory 驗證程式庫。 使用 Linux 和 macOS 驅動程式時，確認已安裝 libcurl。 對於驅動程式 17.2 版和更新版本，這不是明確的相依性，因其不是其他驗證方法或 ODBC 作業的必要項。

• 當 Microsoft Entra 設定包含條件式存取原則，且用戶端為 Windows 10 或 Server 2016 或更新版本時，透過整合式或使用者名稱/密碼進行的驗證可能會失敗。 條件式存取原則要求使用 Web 帳戶管理員 (WAM)，其由適用於 Windows 的驅動程式 17.6 版或更新版本所支援。 若要使用 WAM，請分別在 HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server、HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name> 或 HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> 中針對全域、使用者 DSN 或系統 DSN 範圍的設定建立名為 ADALuseWAM 的新字串，並將其設定為 1 的值。 請注意，使用 WAM 進行驗證並不支援使用 runas 以不同的使用者身分執行應用程式。 Linux 或 macOS 並不支援需要條件式存取原則的案例。

• 若要使用 SQL Server 帳戶使用者名稱與密碼進行連線，您現在可以使用新的 SqlPassword 選項，這是特別適用於 Azure SQL 的建議選項，因為此選項會啟用更安全的連線預設值。

• 若要使用 Microsoft Entra 帳戶使用者名稱與密碼進行連線，請分別利用使用者名稱與密碼來指定連接字串中的 Authentication=ActiveDirectoryPassword 及 UID 和 PWD 關鍵字。

• 若要使用 Windows 整合式或 Microsoft Entra 整合式 (僅限 Windows 與 Linux/macOS 17.6+ 驅動程式) 驗證進行連線，請在連接字串中指定 Authentication=ActiveDirectoryIntegrated。 驅動程式將自動選擇正確的驗證模式。 針對驅動程式 17.7 版或更早版本，不得指定 UID 和 PWD。 從驅動程式 17.8 版開始，會忽略 UID 和 PWD。

• 若要使用 Microsoft Entra 互動式驗證 (僅限 Windows 驅動程式) 進行連線，就必須指定 UID。 針對驅動程式 17.7 版或更早版本，不得指定 PWD。 從驅動程式 17.8 版開始，會忽略 PWD。

• 從 18.1 版開始，預設 Trusted_Connection=Yes 不再使用 Microsoft Entra ID 同盟驗證，並改為使用 SSPI 整合式驗證。 若要針對此選項使用 Microsoft Entra ID， TrustedConnection_UseAAD=Yes 應該設定 。

• ODBC 驅動程式 17.7 版和更低版本在 SQL Server 執行個體上啟用 Microsoft Entra 驗證和強制加密時，會發生連線逾時的已知問題。 SQL Server 錯誤記錄可能包含錯誤訊息，例如：「錯誤：33155、嚴重性：20、狀態：1。伺服器等候同盟驗證權杖時，已引發中斷連線活動。這可能是因為用戶端關閉或伺服器逾時已過期。」。 如果您使用高可用性解決方案，例如Always On 可用性群組或容錯移轉叢集執行個體，SQL Server 的內部叢集通訊可能會受到這個可能會影響資源可用性的行為所影響。 在叢集記錄中，您可能會看到錯誤訊息，例如：[hadrag] Connect to SQL Server ...ODBC Error: [HY000] [Microsoft][ODBC Driver 17 for SQL Server]An unknown error has occurred. Detailed error information is not available. (0)。 ODBC 驅動程式 17.10 版和更新版本修正了此問題，並使用 SQL Server 2022 GDR KB5021522 /CU1 KB5022375，包含此修正的最新驅動程式會隨 SQL Server 安裝一起安裝。 您可以參考 ODBC 資料來源管理員，來確認您已安裝的 ODBC 驅動程式版本。

• 從 ODBC 驅動程式 18.3 版開始，Azure Arc 和 Azure Cloud Shell 支援受控識別 (ActiveDirectoryMSI) 驗證。

使用存取權杖進行驗證

SQL_COPT_SS_ACCESS_TOKEN 預先連線屬性允許使用從 Microsoft Entra ID 取得的存取權杖進行驗證 (而不是使用者名稱與密碼)，同時也會略過驅動程式對存取權杖的協商和取得。 若要使用存取權杖，請將 SQL_COPT_SS_ACCESS_TOKEN 連線屬性設定為指向 ACCESSTOKEN 結構的指標：

typedef struct AccessToken
{
    DWORD dataSize;
    BYTE data[];
} ACCESSTOKEN;

ACCESSTOKEN 是一個可變長度結構，由 4 個位元組的「長度」 且後面接著形成存取權杖之不透明資料的「長度」 位元組所組成。 由於 SQL Server 處理存取權杖的方式，因此，必須展開透過 OAuth 2.0 JSON 回應取得的權杖，讓每個位元組後面都接著一個 0 填補位元組，類似於僅包含 ASCII 字元的 UCS-2 字串。 不過，此權杖是一個不透明的值，而且指定的長度 (以位元組為單位) 不得包含任何 Null 結束字元。 由於其在長度和格式方面有大量限制，因此只能透過 SQL_COPT_SS_ACCESS_TOKEN 連線屬性，以程式設計方式使用這個驗證方法。 沒有對應的 DSN 或連接字串關鍵字。 連接字串不能包含 UID、PWD、Authentication 或 Trusted_Connection 關鍵字。

注意

ODBC Driver 13.1 版僅在 Windows 上支援此驗證。 後續版本在所有平台上都支援此驗證。

Microsoft Entra 驗證範例程式碼

下列範例示範如何使用 Microsoft Entra ID 搭配連線關鍵字來連線到 SQL Server 所需的程式碼。 不需要變更應用程式程式碼本身。 使用 Microsoft Entra ID 進行驗證唯一需要修改的是連接字串或 DSN (如已使用)：

    ...
    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;"
    ...
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...

下列範例示範如何使用 Microsoft Entra 存取權杖驗證來連線到 SQL Server 所需的程式碼。 在此案例中，您必須修改應用程式程式碼來處理存取權杖，並設定相關聯的連線屬性。

    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Encrypt=yes;"
    SQLCHAR accessToken[] = "eyJ0eXAiOi..."; // In the format extracted from an OAuth JSON response
    ...
    DWORD dataSize = 2 * strlen(accessToken);
    ACCESSTOKEN *pAccToken = malloc(sizeof(ACCESSTOKEN) + dataSize);
    pAccToken->dataSize = dataSize;
    // Expand access token with padding bytes
    for(int i = 0, j = 0; i < dataSize; i += 2, j++) {
        pAccToken->data[i] = accessToken[j];
        pAccToken->data[i+1] = 0;
    }
    ...
    SQLSetConnectAttr(hDbc, SQL_COPT_SS_ACCESS_TOKEN, (SQLPOINTER)pAccToken, SQL_IS_POINTER);
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...
    free(pAccToken);

以下是與 Microsoft Entra 互動式驗證搭配使用的範例連接字串。 其並未包含 PWD 欄位，因為會在 Azure 驗證畫面上輸入密碼。

SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"

下列範例連接字串可與 Microsoft Entra 受控識別驗證搭配使用。 如果使用使用者指派的身分識別，請將 UID 設定為使用者識別的物件/用戶端識別碼。

// For system-assigned identity,
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Authentication=ActiveDirectoryMsi;Encrypt=yes;"
...
// For user-assigned identity with object ID equals to myObjectId
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;"

在 Linux/macOS 上使用 ADFS 同盟帳戶的考量

從 17.6 版開始，適用於 Linux 與 macOS 的驅動程式支援搭配使用者名稱/密碼 (ActiveDirectoryPassword) 或 Kerberos (ActiveDirectoryIntegrated) 使用 Microsoft Entra ADFS 同盟帳戶進行驗證。 使用整合模式時，會有一些取決於平台的限制。

當 UPN 尾碼與 Kerberos 領域不同 (也就是使用替代的 UPN 尾碼) 的使用者進行驗證時，必須在取得 Kerberos 票證時使用企業主體選項 (搭配 kinit 使用 -E 選項，並以 user@federated-domain 的格式提供主體名稱)。 如此一來，可讓驅動程式正確判斷同盟網域與 Kerberos 領域。

您可以透過檢查 klist 命令的輸出，來確認有適當的 Kerberos 票證可供使用。 如果同盟網域與 Kerberos 領域及 UPN 尾碼相同，主體名稱的格式將會是 user@realm。 如果其為不同，主體名稱的格式應該會是 user@federated-domain@realm。

Linux

在 SUSE 11 上，預設的 Kerberos 程式庫版本 (1.6.x) 並不支援使用替代 UPN 尾碼所需的企業主體選項。 若要搭配 Azure AD 整合式驗證使用替代 UPN 尾碼，請將 Kerberos 程式庫升級到 1.7 或更新版本。

在 Alpine Linux 上，預設的 libcurl 並不支援進行 Microsoft Entra 整合式驗證所需的 SPNEGO/Kerberos 驗證。

macOS

系統 Kerberos 程式庫 kinit 能透過 --enterprise 選項支援企業主體，但也會隱含地執行名稱標準化，其會避免使用替代 UPN 尾碼。 若要搭配 Microsoft Entra 整合式驗證使用替代 UPN 尾碼，請透過 brew install krb5 安裝較新的 Kerberos 程式庫，並以上面所述的方式搭配 -E 選項使用其 kinit。

相關內容

• 適用於使用 Microsoft Entra 驗證之 Azure SQL Database 的權杖型驗證支援
• 使用整合式驗證