Использование идентификатора Microsoft Entra с драйвером ODBC

Примечание.

Хотя Microsoft Entra ID — это новое имя для Azure Active Directory (Azure AD), во избежание нарушения существующих сред, Azure AD по-прежнему остается в таких жестко закодированных элементах, как поля интерфейса пользователя, поставщики подключения, коды ошибок и командлеты. В этой статье два имени являются взаимозаменяемыми.

Цель

Драйвер Microsoft ODBC для SQL Server версии 13.1 и выше позволяет приложениям ODBC подключаться к Базе данных Azure SQL или Управляемому экземпляру Azure SQL с помощью удостоверений в Microsoft Entra ID. Проверку подлинности можно выполнить с помощью имени пользователя и пароля, маркера доступа Microsoft Entra, управляемого удостоверения Microsoft Entra (17.3+) или встроенной проверки подлинности Windows в федеративной , присоединенной к домену среде (17.6+ в Linux или macOS). Для драйвера ODBC версии 13.1 проверка подлинности маркера доступа Microsoft Entra доступна исключительно для Windows. Драйвер ODBC версии 17 и более поздней поддерживает эту проверку подлинности на всех платформах (Windows, Linux и macOS). Новый интерактивный метод проверки подлинности Microsoft Entra, поддерживающий многофакторную проверку подлинности, представлен в ODBC Driver версии 17.1 для Windows. Новый метод аутентификации управляемого удостоверения Microsoft Entra был добавлен в ODBC Driver версии 17.3.1.1 как для удостоверений, назначаемых системой, так и для удостоверений, назначаемых пользователем. Все эти действия выполняются с помощью новых ключевых слов строки подключения и имени DSN, а также атрибутов подключения.

Чтобы использовать проверку подлинности Microsoft Entra, необходимо настроить источник данных SQL Azure. Дополнительные сведения см. в разделе о настройке и администрировании проверки подлинности Microsoft Entra с помощью Azure SQL.

Примечание.

Драйвер ODBC в Linux и macOS до версии 17.6 поддерживает только аутентификацию Microsoft Entra непосредственно через идентификатор Microsoft Entra. Если вы используете проверку подлинности имени пользователя и пароля Microsoft Entra из клиента Linux или macOS, а конфигурация Microsoft Entra требует, чтобы клиент прошел проверку подлинности в конечной точке служб федерации Microsoft Entra, проверка подлинности может завершиться ошибкой. В версии драйвера 17.6 это ограничение снято.

Новые или измененные ключевые слова строки подключения и имени DSN

Ключевое слово Authentication можно использовать при подключении через имя DSN или строку подключения для управления режимом проверки подлинности. Значение, заданное в строке подключения, переопределяет значение в DSN, если оно указано. Значение предварительного атрибута параметра Authentication вычисляется на основе значений строки подключения и имени DSN.

Имя.	Значения/По умолчанию	Описание
`Authentication`	`(not set)`(по умолчанию), `(empty string)`, `SqlPasswordActiveDirectoryIntegratedActiveDirectoryInteractiveActiveDirectoryMsiActiveDirectoryServicePrincipalActiveDirectoryPassword`[ не рекомендуется]	Управляет режимом проверки подлинности. `(not set)` — режим проверки подлинности, определенный другими ключевыми словами (существующие устаревшие параметры подключения.) `(empty string)` — (только строка подключения.) Переопределите и сбросьте значение, заданное в DSN `Authentication`. `SqlPassword` — прямая проверка подлинности в SQL с помощью имени пользователя и пароля. `ActiveDirectoryIntegrated` - Только драйвер для Windows, Linux/Mac 17.6+. Аутентификация с использованием федеративных учетных данных Windows через Microsoft Entra ID с интегрированной аутентификацией. `ActiveDirectoryInteractive` - Только драйвер Windows. Аутентификация с помощью удостоверения Microsoft Entra с использованием интерактивной аутентификации. `ActiveDirectoryMsi` — проверка подлинности с помощью управляемого удостоверения Microsoft Entra. Для пользовательского назначенного удостоверения установите UID в идентификатор клиента удостоверения для Служба приложений Azure или Azure Container Instance; в противном случае используйте его идентификатор объекта. Для назначаемого системой удостоверения UID не требуется. `ActiveDirectoryServicePrincipal` — Аутентификация с помощью сервисного принципала Microsoft Entra (17.7+). В качестве UID задается идентификатор клиента субъекта-службы. В переменную PWD (пароль) задается секрет клиента. `ActiveDirectoryPassword` — [DEPRECATED] Проверка подлинности с помощью удостоверения Microsoft Entra с помощью имени пользователя и пароля. `ActiveDirectoryPassword` не рекомендуется к использованию. Дополнительные сведения см. в разделе ActiveDirectoryPassword не рекомендуется.
`Encrypt`	`(not set)`(по умолчанию), `Yes`/`Mandatory` (версии 18.0 и позднее),`OptionalNo`/(версии 18.0 и позднее), `Strict` (версии 18.0 и позднее)	Управляет шифрованием соединения. Если вы явно не задаёте шифрование, в драйвере 17 по умолчанию используется `Yes`, если значение предатрибута `Authentication` не равно `none` или задано `SQL_COPT_SS_ACCESS_TOKEN`; в противном случае по умолчанию используется `No`. В версиях драйвера 18.0.1 и более поздних по умолчанию используется `Yes` (`Mandatory`). Аутентификация и шифрование остаются отдельными настройками. Если `SQL_COPT_SS_AUTHENTICATION` переопределяет значение pre-attribute у `Authentication`, явно устанавливайте шифрование в DSN, строка подключения или атрибуте соединения `SQL_COPT_SS_ENCRYPT`.

Новые или измененные атрибуты подключения

Следующие атрибуты подключения были добавлены или изменены для поддержки аутентификации Microsoft Entra. Если атрибут подключения имеет соответствующее ключевое слово строки подключения или имени DSN и установлен, у этого атрибута будет более высокий приоритет.

Атрибут	Тип	Значения	По умолчанию.	Описание
`SQL_COPT_SS_AUTHENTICATION`	`SQL_IS_INTEGER`	`SQL_AU_NONE`, `SQL_AU_PASSWORD`, `SQL_AU_AD_INTEGRATEDSQL_AU_AD_PASSWORDSQL_AU_AD_INTERACTIVESQL_AU_AD_MSISQL_AU_AD_SPASQL_AU_RESET`	(не задано)	См. описание ключевого слова `Authentication` выше. `SQL_AU_NONE` предоставляется для явного переопределения заданного значения `Authentication` в имени DSN и (или) строке подключения, в то время как `SQL_AU_RESET` отменяет атрибут, если он был установлен, и значение имени DSN или строки подключения получает более высокий приоритет.
`SQL_COPT_SS_ACCESS_TOKEN`	`SQL_IS_POINTER`	Указатель на `ACCESSTOKEN` или NULL	NULL	Если значение не равно NULL, указывает используемый маркер доступа Microsoft Entra. Указание маркера доступа, а также ключевых слов строки подключения `UID`, `PWD`, `Trusted_Connection`, `Authentication` или эквивалентных атрибутов является ошибкой. ПРИМЕЧАНИЕ. Драйвер ODBC версии 13.1 поддерживает этот параметр только в Windows.
`SQL_COPT_SS_ENCRYPT`	`SQL_IS_INTEGER`	`SQL_EN_OFF`, `SQL_EN_ON`	(см. описание)	Управляет запросом клиента на шифрование. `SQL_EN_OFF` не препятствует тому, что сервер требует шифрования. В Драйвере 17, если вы явно не установили шифрование, а значение предварительного атрибута `Authentication` не равно `none` или `SQL_COPT_SS_ACCESS_TOKEN` установлено, то по умолчанию — `SQL_EN_ON`. В противном случае драйвер 17 по умолчанию использует `SQL_EN_OFF`. В версиях Driver 18.0.1 и более поздних по умолчанию используется значение `SQL_EN_ON` независимо от аутентификации, если шифрование не устанавливается явно. Если `SQL_COPT_SS_AUTHENTICATION` переопределяет значение пре-атрибута `Authentication`, явно установите шифрование в DSN, строке подключения или этом атрибуте. Для поведения при шифровании и проверке сертификатов см. Примеры строк соединения.
`SQL_COPT_SS_OLDPWD`	-	-	-	Не поддерживается с идентификатором Microsoft Entra, так как изменение пароля для субъектов Microsoft Entra невозможно выполнить через подключение ODBC. Истечение срока действия пароля для проверки подлинности 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_COPT_SS_AUTHENTICATION` укажите значение `SQL_AU_AD_INTEGRATED`. Обеспечивает принудительное использование аутентификации Windows (Kerberos в Linux и macOS) для валидации доступа на сервер. Если используется проверка подлинности Windows, драйвер пропускает значения идентификатора пользователя и пароля, предоставленные в процессе обработки `SQLConnect`, `SQLDriverConnect` или `SQLBrowseConnect`.

ActiveDirectoryPassword объявлен устаревшим

Important

Параметр аутентификации ActiveDirectoryPassword (аутентификация по паролю Microsoft Entra ID) устарел в драйверах Microsoft SQL. Этот высокорисковый сценарий аутентификации несовместим с обязательной многофакторной аутентификацией Microsoft Entra (MFA) и может не работать в арендаторах, где требуется MFA. Запланируйте переход на другой метод аутентификации Microsoft Entra.

Microsoft Entra ID проверка подлинности паролей основана на предоставлении учетных данных владельца ресурса OAuth 2.0 ( ROPC), что позволяет приложению войти в систему, напрямую обрабатывая пароль.

Microsoft рекомендует не использовать поток ROPC, так как он несовместим с MFA. В большинстве случаев более безопасные альтернативные варианты доступны и рекомендуется. Этот поток требует высокой степени доверия к приложению и несет риски, которые не присутствуют в других потоках. Используйте этот поток только в том случае, если более безопасные потоки не являются жизнеспособными. Корпорация Майкрософт отойдет от этого потока проверки подлинности с высоким риском, чтобы защитить пользователей от вредоносных атак. Дополнительные сведения см. в статье "Планирование обязательной многофакторной проверки подлинности для Azure".

Когда пользователь присутствует при входе в систему, используйте аутентификацию ActiveDirectoryInteractive или ActiveDirectoryIntegrated, чтобы записи в журнале аудита относились к вошедшему пользователю и применялись политики условного доступа.

Для сценариев взаимодействия между службами без участия пользователя следуйте рекомендациям по использованию служебной учетной записи Microsoft Entra:

Если приложение работает в инфраструктуре Azure, используйте ActiveDirectoryMSI (или ActiveDirectoryManagedIdentity в некоторых драйверах). Управляемые удостоверения устраняют затраты на обслуживание и смену секретов и сертификатов.
Если управляемое удостоверение недоступно (например, приложение работает вне Azure), используйте ActiveDirectoryServicePrincipal. Если драйвер это поддерживает, предпочтительнее использовать клиентский сертификат вместо секрета клиента. При использовании сертификата закрытый ключ остается на клиенте, и только подписанное утверждение отправляется в Microsoft Entra для проверки подлинности клиента. Если ключ хранится в аппаратном модуле (например, TPM или HSM) или помечен как неэкспортируемый, его нельзя экспортировать в виде строки, как это можно сделать с секретом клиента.
Не используйте Microsoft Entra учетную запись пользователя в качестве учетной записи службы.

Дополнения пользовательского интерфейса для идентификатора Microsoft Entra (только драйвер Windows)

Интерфейсы настройки и подключения DSN драйвера были улучшены с добавлением дополнительных опций, необходимых для аутентификации с Microsoft Entra ID.

Создание и редактирование DSN в пользовательском интерфейсе

При создании или редактировании существующего DSN с помощью пользовательского интерфейса установки драйвера можно использовать параметры проверки подлинности Microsoft Entra:

Authentication=ActiveDirectoryIntegrated Встроенная проверка подлинности Microsoft Entra для Azure SQL

Экран создания и редактирования DSN с выбранной интегрированной проверкой подлинности Microsoft Entra.

Authentication=ActiveDirectoryPassword для проверки подлинности имени пользователя и пароля Microsoft Entra в SQL Azure

Примечание.

ActiveDirectoryPassword устарел. Дополнительные сведения см. в разделе ActiveDirectoryPassword не рекомендуется.

Экран создания и редактирования DSN с выбранной аутентификацией Microsoft Entra Password.

Authentication=ActiveDirectoryInteractive для интерактивной аутентификации Microsoft Entra в Azure SQL

Экран создания и редактирования DSN с выбранной интерактивной проверкой подлинности Microsoft Entra.

Примечание.

Начиная с драйвера версии 17.9, поведение интерактивной проверки подлинности изменилось. Пользователи всегда будут получать запрос на ввод учетных данных, если только драйвер не кэширует допустимый маркер доступа. Это изменение предотвращает возможность пользователей на устройствах, присоединенных к Microsoft Entra, пропустить запрос и автоматически войти с использованием кэшированных учетных данных при использовании ActiveDirectoryInteractive проверки подлинности.

Authentication=SqlPassword для проверки подлинности имени пользователя и пароля в SQL Server и Azure SQL

Экран создания и редактирования DSN с использованием проверки подлинности SQL Server.

Trusted_Connection=Yes для встроенной устаревшей аутентификации SSPI для Windows.

Экран создания и редактирования DSN с выбранной интеграцией проверки подлинности Windows.

Authentication=ActiveDirectoryMsi Для аутентификации с использованием управляемого удостоверения Microsoft Entra

Экран создания и редактирования DSN с выбранной аутентификацией через управляемую идентичность службы.

Authentication=ActiveDirectoryServicePrincipal для аутентификации учетной записи службы Microsoft Entra

Экран создания и редактирования DSN с аутентификацией с помощью учетной записи службы Microsoft Entra.

Семь параметров соответствуют Trusted_Connection=Yes (устаревшая встроенная проверка подлинности только с использованием Windows SSPI), Authentication=ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi и ActiveDirectoryServicePrincipal соответственно.

Диалоговое окно SQLDriverConnect (только драйвер Windows)

Диалоговое окно запроса, отображаемое SQLDriverConnect при запросе сведений, необходимых для завершения подключения, содержит четыре новых варианта проверки подлинности Microsoft Entra:

Диалоговое окно входа SQL Server, отображаемое SQLDriverConnect.

Эти опции соответствуют шести доступным установкам в интерфейсе настройки DSN.

Примеры строк подключения

Примечание.

Описания шифрования и проверки сертификатов в этих примерах применяются к обычным удалённым соединениям без DSN или переопределений атрибутов соединения, параметров реестра Windows Force Protocol Encryption или внутренних обратных вызовов проверки сертификатов Windows. Они описывают не-Strictшифрование. Шифрование только на этапе входа защищает обмен данными аутентификации, а не последующие данные приложений.

С Encrypt=yes и TrustServerCertificate=no (по умолчанию) драйверы 17 и 18 запрашивают полносессионное шифрование и проверяют сертификат сервера. Если клиент устанавливает Encrypt=no, но сервер требует полносессионного шифрования, драйвер 17 не выбирает обычную проверку сертификата для этого запроса только к серверу. Драйвер 18 проверяет согласованное состояние зашифрованного полного сеанса и проверяет сертификат, кроме случаев, когда TrustServerCertificate=yes. В обычном пути без StrictTrustServerCertificate=yes подавляет нормальную валидацию; шифрование, принудительно заданное через реестр Windows, может выбирать валидацию независимо от этой настройки, а внутренний обратный вызов Windows может заменить обычный путь валидации.

Устаревший синтаксис проверки подлинности SQL Server. Сертификат сервера не проверяется, и шифрование используется только в том случае, если сервер применяет его принудительно. Имя пользователя и пароль передаются в строку подключения.

server=Server;database=Database;UID=UserName;PWD=<password>;Encrypt=no;TrustServerCertificate=yes;
Новый синтаксис проверки подлинности SQL. Используя Authentication=SqlPassword и опуская шифрование, как показано, драйверы 17 и 18 по умолчанию запрашивают полносессионное шифрование. Драйвер проверяет сертификат сервера с использованием TrustServerCertificate=no по умолчанию. Имя пользователя и пароль находятся в строке подключения.

server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=SqlPassword;
Интегрированная аутентификация Windows (Kerberos в Linux и macOS) с использованием SSPI (для SQL Server или SQL IaaS) — текущий синтаксис. При Encrypt=no, полносессионное шифрование используется только в том случае, если сервер этого требует. Для этого запроса только к серверу Драйвер 17 не выбирает обычную проверку сертификата; Драйвер 18 выполняет проверку с использованием значения по умолчанию TrustServerCertificate=no.

server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;
(только драйвер Windows.) Встроенная проверка подлинности Windows с помощью SSPI (если целевая база данных находится в SQL Server или SQL Server на виртуальных машинах Azure) — новый синтаксис. Используя Authentication=ActiveDirectoryIntegrated и опуская шифрование, как показано, драйверы 17 и 18 по умолчанию запрашивают полносессионное шифрование. Драйвер проверяет сертификат сервера с использованием значения по умолчанию TrustServerCertificate=no.

server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;
Microsoft Entra аутентификация имени пользователя и пароля (если целевая база данных находится в База данных SQL Azure или Управляемый экземпляр SQL Azure). Явно заданный запрос Encrypt=yes требует полносессионного шифрования. Драйвер проверяет сертификат сервера с использованием значения по умолчанию TrustServerCertificate=no. Имя пользователя и пароль находятся в строка подключения.

Примечание.

ActiveDirectoryPassword устарел. Дополнительные сведения см. в разделе ActiveDirectoryPassword не рекомендуется.

server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;
(Windows и Linux/macOS 17.6 и более поздние версии, только драйвер.) Интегрированная аутентификация Windows с использованием ADAL или Kerberos, которая включает обмен учетных данных учетной записи Windows на токен доступа Microsoft Entra, при условии, что целевая база данных находится в Azure SQL. Явный запрос Encrypt=yes требует полносессионного шифрования. Драйвер проверяет сертификат сервера с использованием параметра по умолчанию TrustServerCertificate=no. В Linux/macOS должен быть доступен подходящий билет Kerberos. Для получения дополнительной информации см. раздел «Соображения по использованию федеративных учётных записей ADFS на Linux/macOS» и «Использование интегрированной аутентификации».

server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;
(Только драйвер Windows.) Microsoft Entra Interactive Authentication использует многофакторную аутентификацию Microsoft Entra для настройки соединения. Вы можете опустить UID с драйвером 17.8 и более поздними версиями или установить его в значение учетной записи пользователя для аутентификации. Когда вы указываете UID, диалог входа может не предложить возможность выбрать другой аккаунт. Чтобы использовать другую учётную запись, измените UID перед подключением или опустите с драйвером 17.8 и более поздними версиями. Драйвер открывает диалоговое окно аутентификации Azure, чтобы пользователь мог завершить дополнительную проверку.

server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;
Проверка подлинности управляемого удостоверения Microsoft Entra может использовать назначаемое системой или назначаемое пользователем управляемое удостоверение. Для пользовательского назначенного удостоверения установите UID в идентификатор клиента удостоверения для Служба приложений Azure или Azure Container Instance; в противном случае используйте его идентификатор объекта. Для назначаемого системой удостоверения 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=<password>;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Замечания

При использовании параметров Microsoft Entra с драйвером ODBC для Windows до версии 17.4.2 убедитесь, что библиотека проверки подлинности Active Directory для SQL Server установлена. При использовании драйверов Linux и macOS убедитесь, что libcurl установлена. Для драйвера версии 17.2 и более поздних эта зависимость не является явной, так как она не обязательна для других методов проверки подлинности или операций ODBC.
Если конфигурация Microsoft Entra включает политики условного доступа, а клиент — Windows 10, Server 2016 или более поздней версии, проверка подлинности с использованием интегрированной аутентификации или имени пользователя и пароля может завершиться неудачно. Политики условного доступа требуют использования диспетчера веб-учетных записей (WAM), который поддерживается в драйвере 17.6 или более поздней версии для Windows. Чтобы использовать WAM, создайте новое строковое значение с именем ADALuseWAM в 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-конфигурации соответственно, и задайте для него значение 1. Обратите внимание, что при проверке подлинности с помощью WAM не поддерживается запуск приложения от имени другого пользователя с помощью runas. Сценарии, для которых требуются политики условного доступа, не поддерживаются для Linux или macOS.
Чтобы подключиться с помощью имени пользователя и пароля учетной записи SQL Server, теперь можно использовать новый параметр SqlPassword (рекомендуется для Azure SQL, так как этот параметр обеспечивает более безопасные значения по умолчанию для подключений).
Чтобы подключиться с помощью имени пользователя и пароля учетной записи Microsoft Entra, укажите Authentication=ActiveDirectoryPassword в строка подключения и UIDPWD ключевые слова с именем пользователя и паролем соответственно.

Примечание.

ActiveDirectoryPassword устарел. Дополнительные сведения см. в разделе ActiveDirectoryPassword не рекомендуется.
Чтобы подключиться с помощью встроенной проверки подлинности Windows или Microsoft Entra (Windows и Linux/macOS 17.6+, только драйвер), укажите Authentication=ActiveDirectoryIntegrated в строке подключения. Драйвер автоматически выбирает правильный режим проверки подлинности. Для драйверов версии 17.7 и более ранних версий UID и PWD не задаются. Начиная с драйвера версии 17.8 UID и PWD игнорируются.
Чтобы подключиться с помощью интерактивной аутентификации Microsoft Entra (только драйвер Windows), можно опустить UID при использовании драйвера 17.8 и более поздних версий или указать в нем учётную запись пользователя для аутентификации. Диалог входа может не позволить сменить аккаунт при вводе UID. Чтобы использовать другую учётную запись, измените UID перед подключением или не указывайте его с драйвером 17.8 и более поздними версиями. Версии драйверов 17.7 и более ранние требуют UID и запрещают PWD. Начиная с драйвера версии 17.8 PWD игнорируется.
Начиная с версии 18.1, Trusted_Connection=Yes больше не использует федеративную проверку подлинности идентификатора Microsoft Entra ID по умолчанию и использует встроенную SSPI. Чтобы использовать идентификатор Microsoft Entra для этого параметра, TrustedConnection_UseAAD=Yes необходимо настроить.
Драйверы ODBC версий 17.7 и ниже имеют известную проблему с временем ожидания подключения, если включены проверка подлинности Microsoft Entra и принудительное шифрование на экземпляре SQL Server. Журнал ошибок 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 проверка подлинности управляемого удостоверения (ActiveDirectoryMSI) поддерживается в Azure Arc и Azure Cloud Shell.

Проверка подлинности с помощью токена доступа

Атрибут 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 обрабатывает маркеры доступа, один из них, полученный с помощью ответа JSON OAuth 2.0, должен быть расширен таким образом, чтобы за каждым байтом был нулевой дополнительный байт аналогично строке UCS-2, содержащей только символы ASCII. Токен — это непрозрачное значение и длина, указанная в байтах, НЕ должна включать нулевой терминатор. По причине существенных ограничений длины и формата этот метод проверки подлинности доступен только программно с помощью атрибута подключения SQL_COPT_SS_ACCESS_TOKEN.

Вы должны сохранять ACCESSTOKEN, пока существует дескриптор соединения. В противном случае могут возникнуть ошибки доступа. Когда вы используете менеджер драйверов Windows ODBC, указатель токена является частью ключа пула соединений, поэтому другой указатель выбирает другой пул. Сохраняйте буфер, связанный с тем же идентификатором, когда заменяете просроченный токен. Обновление буфера не меняет идентификатор уже аутентифицированного соединения.

Caution

В Linux и macOS пул соединений unixODBC не использует SQL_COPT_SS_ACCESS_TOKEN для различения идентичностей. Когда вы используете ту же строку подключения, запрос на соединение с другим токеном может повторно использовать пуловое соединение, аутентифицированное с предыдущей учетной записью. Если ваш процесс соединяется с токенами для разных учетных записей, отключите пул unixODBC перед запуском: установите Pooling=No в разделе [ODBC] действующего файла odbcinst.ini и убедитесь, что ваше приложение и его библиотеки не включают пул ODBC. Перезапустите существующие процессы приложений после изменения конфигурации. Не полагайтесь на изменение указателей токенов для изоляции идентичностей.

Нет подходящего ключевого слова DSN или строки подключения. Строка подключения не должна содержать ключевые слова UID, PWD, Authentication или Trusted_Connection.

Примечание.

Драйвер ODBC версии 13.1 поддерживает такую проверку подлинности только в Windows. Последующие версии поддерживают эту проверку подлинности на всех платформах.

Пример кода проверки подлинности Microsoft Entra

В следующем примере показан код, необходимый для подключения к SQL Server с помощью идентификатора Microsoft Entra с ключевыми словами подключения. Нет необходимости изменять сам код приложения. Строка подключения или DSN, если он используется, является единственным изменением, необходимым для использования идентификатора Microsoft Entra для проверки подлинности:

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

В следующем примере показан код, необходимый для подключения к SQL Server с помощью проверки подлинности маркера доступа Microsoft Entra. В этом случае необходимо изменить код приложения для обработки маркера доступа и настроить связанный атрибут подключения.

    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;"

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-20

Использование идентификатора Microsoft Entra с драйвером ODBC

Цель

Новые или измененные ключевые слова строки подключения и имени DSN

Новые или измененные атрибуты подключения

ActiveDirectoryPassword объявлен устаревшим

Дополнения пользовательского интерфейса для идентификатора Microsoft Entra (только драйвер Windows)

Создание и редактирование DSN в пользовательском интерфейсе

Диалоговое окно SQLDriverConnect (только драйвер Windows)

Примеры строк подключения

Замечания

Проверка подлинности с помощью токена доступа

Пример кода проверки подлинности Microsoft Entra

Рекомендации по использованию федеративных учетных записей ADFS в Linux или macOS

Linux

macOS

Связанный контент

Обратная связь

Дополнительные ресурсы