搭配 ODBC 驅動程式使用 Microsoft Entra 識別碼
注意
雖然 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 資料庫 或 Azure SQL 受控執行個體。 驗證可以透過使用者名稱和密碼、Microsoft Entra 存取令牌、Microsoft Entra 受控識別(17.3+)或已加入網域的同盟環境中整合式 Windows 驗證來完成(Linux/macOS 上的 17.6+ )。 針對 ODBC Driver 13.1 版,Microsoft Entra 存取令牌驗證 僅限 Windows。 ODBC Driver 17 版和更新版本支援跨所有平台 (Windows、Linux 及 macOS) 進行此驗證。 支援多重要素驗證的新 Microsoft Entra 互動式驗證方法已在適用於 Windows 的 ODBC Driver 17.1 版中引進。 ODBC Driver 17.3.1.1.1 版中新增了新的 Microsoft Entra 受控識別驗證方法,適用於系統指派和使用者指派的受控識別。 這些選項全部都是使用新的 DSN 和連接字串關鍵字,以及連線屬性來完成。
若要使用 Microsoft Entra 驗證,您必須設定 Azure SQL 數據源。 如需詳細資訊,請參閱使用 Azure SQL 設定和管理 Microsoft Entra 驗證。
注意
17.6 版之前的Linux和macOS上的ODBC驅動程式僅支援直接針對 Microsoft Entra 識別碼進行 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 |
(未設定) | 控制驗證模式。
|
||||||||||||||||||
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 |
SQL_AU_NONE 、SQL_AU_PASSWORD 、SQL_AU_AD_INTEGRATED 、SQL_AU_AD_PASSWORD 、SQL_AU_AD_INTERACTIVE 、SQL_AU_AD_MSI 、、、 SQL_AU_AD_SPA SQL_AU_RESET |
(未設定) | 請參閱上方的 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 |
(請參閱描述) | 控制連接的加密。 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
適用於 Microsoft Entra 整合式驗證至 Azure SQL
Authentication=ActiveDirectoryPassword
適用於 Azure SQL 的 Microsoft Entra 使用者名稱/密碼驗證
Authentication=ActiveDirectoryInteractive
適用於 Microsoft Entra 互動式驗證至 Azure SQL
注意
自驅動程式 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 驅動程式)
SQLDriver 所顯示的提示對話框 連線 當它要求完成連線所需的資訊時,包含 Microsoft Entra 驗證的四個新選項:
這些選項對應至上述 DSN 設定 UI 中相同的六個可用選項。
範例連接字串
SQL Server 驗證:舊版語法。 伺服器憑證不會經過驗證,而且只有在伺服器強制進行加密時,才會使用加密。 使用者名稱/密碼會在連接字串中傳遞。
server=Server;database=Database;UID=UserName;PWD=Password;Encrypt=no;TrustServerCertificate=yes;
SQL 驗證:新語法。 用戶端會要求加密 (
Encrypt
的預設值是true
),且無論加密設定為何 (除非將TrustServerCertificate
設定為true
),都會驗證伺服器憑證。 使用者名稱/密碼會在連接字串中傳遞。server=Server;database=Database;UID=UserName;PWD=Password;Authentication=SqlPassword;
(向 SQL Server 或 SQL IaaS) 使用 SSPI 的整合式 Windows 驗證 (Linux 和 macOS 上的 Kerberos):目前的語法。 除非伺服器需要加密,否則不會驗證伺服器憑證。
server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;
(僅限 Windows 驅動程式。使用 SSPI 的整合式 Windows 驗證(如果目標資料庫位於 SQL Server 或 Azure VM 上的 SQL Server)- 新的語法。 用戶端會要求加密 (
Encrypt
的預設值是true
),且無論加密設定為何 (除非將TrustServerCertificate
設定為true
),都會驗證伺服器憑證。server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;
Microsoft Entra 使用者名稱/密碼驗證(如果目標資料庫位於 Azure SQL 資料庫 或 Azure SQL 受控執行個體)。 無論加密設定為何,都會驗證伺服器憑證 (除非將
TrustServerCertificate
設定為true
)。 使用者名稱/密碼會在連接字串中傳遞。server=Server;database=Database;UID=UserName;PWD=Password;Authentication=ActiveDirectoryPassword;Encrypt=yes;
(僅限 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;
(僅限 Windows 驅動程式。Microsoft Entra Interactive Authentication 會使用 Microsoft Entra 多重要素驗證技術來設定連線。 在此模式中,藉由提供登入標識符,就會觸發 Azure 驗證對話方塊,並讓使用者輸入其他驗證來完成連線。 使用者名稱會在連接字串中傳遞。
server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;
Microsoft Entra 受控識別驗證會使用系統指派或使用者指派的受控識別來進行驗證,以設定連線。 針對使用者指派的身分識別,UID 會設定為使用者身分識別的物件標識符。
針對系統指派的身分識別:
server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;
針對物件識別碼等於
myObjectId
的使用者指派身分識別:server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;
Microsoft Entra 服務主體驗證
server=Server;database=Database;UID=clientId;PWD=clientSecret;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 或更新版本時,透過整合式或使用者名稱/密碼進行驗證可能會失敗。 條件式存取原則需要使用適用於 Windows 的驅動程式 17.6 版或更新版本支援的 Web 帳戶管理員 (WAM)。 若要使用 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
的新字串或 DWORD 值,並將其設定為 1 的值。 請注意,使用 WAM 進行驗證並不支援使用runas
以不同的使用者身分執行應用程式。 Linux 或macOS不支援需要條件式存取原則的案例。若要使用 SQL Server 帳戶使用者名稱與密碼進行連線,您現在可以使用新的
SqlPassword
選項,這是特別適用於 Azure SQL 的建議選項,因為此選項會啟用更安全的連線預設值。若要使用 Microsoft Entra 帳戶使用者名稱和密碼進行連線,請分別使用使用者名稱和密碼,在 連接字串
PWD
UID
和 關鍵詞中指定Authentication=ActiveDirectoryPassword
。若要使用 Windows 整合式或 Microsoft Entra Integrated 連線(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
應該設定 。當 SQL Server 實例上啟用 Microsoft Entra 驗證和強制加密時,ODBC 驅動程式 17.7 版和更低版本有連線逾時已知問題。 SQL Server 錯誤記錄可能包含錯誤訊息,例如:「錯誤:33155、嚴重性:20、狀態:1。伺服器正在等候同盟驗證令牌時引發中斷連線事件。這可能是因為客戶端關閉或伺服器逾時已過期。」。 如果您使用高可用性解決方案,例如 AlwaysOn 可用性群組或故障轉移叢集實例,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 所需的程式碼。 不需要變更應用程式程式碼本身。 如果使用 連接字串,或 DSN 是唯一使用 Microsoft Entra ID 進行驗證所需的修改:
...
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;PWD=myPass;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 的驅動程式支援使用使用者名稱/密碼 () 或 Kerberos 的ActiveDirectoryPassword
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 後綴所需的企業主體選項。 若要搭配 Microsoft Entra 整合式驗證使用替代 UPN 後綴,請將 Kerberos 連結庫升級為 1.7 或更新版本。
在Alpine Linux上,預設值 libcurl
不支援 Microsoft Entra 整合式驗證所需的SPNEGO/Kerberos 驗證。
macOS
系統 Kerberos 程式庫 kinit
能透過 --enterprise
選項支援企業主體,但也會隱含地執行名稱標準化,其會避免使用替代 UPN 尾碼。 若要搭配 Microsoft Entra 整合式驗證使用替代 UPN 後綴,請透過 brew install krb5
安裝較新的 Kerberos 連結庫,並使用其 kinit
搭配 -E
選項,如上所述。