Аутентификация Microsoft Entra с mssql-python

Microsoft Entra ID предоставляет аутентификацию на основе идентичности для База данных SQL Azure, Управляемый экземпляр SQL Azure и SQL Database в Microsoft Fabric через драйвер mssql-python. Аутентификация Microsoft Entra предлагает следующие возможности поверх SQL-аутентификации:

Централизованное управление идентификацией через Microsoft Entra ID.
Аутентификация на основе токенов, которая устраняет необходимость в паролах.
Поддержка политики условного доступа.
Управляемые идентичности для приложений, размещённых в Azure.

Драйвер mssql-python поддерживает семь режимов аутентификации Microsoft Entra, все они настраиваются с помощью ключевого слова Authentication в строке подключения.

Режимы проверки подлинности

Установите ключевое слово Authentication в строке подключения на одно из следующих значений:

Значение аутентификации	Описание
`ActiveDirectoryDefault`	Использует `DefaultAzureCredential`, который автоматически пробует несколько методов.
`ActiveDirectoryInteractive`	Интерактивный вход через браузер.
`ActiveDirectoryDeviceCode`	Ввод кода в https://microsoft.com/devicelogin.
`ActiveDirectoryPassword`	Имя пользователя и пароль с Microsoft Entra ID. Устаревшие.
`ActiveDirectoryMSI`	Управляемая идентификация (системная или пользовательская).
`ActiveDirectoryServicePrincipal`	Принципал сервиса с идентификатором клиента и секретом.
`ActiveDirectoryIntegrated`	Windows интегрирована с Microsoft Entra ID (Kerberos).

Замечание

Режимы ActiveDirectoryDefault, ActiveDirectoryInteractive и ActiveDirectoryDeviceCode требуют пакет azure-identity. Установите это с pip install azure-identity.

DefaultAzureCredential (учетные данные Azure по умолчанию)

Режим ActiveDirectoryDefault использует DefaultAzureCredential из Azure Identity SDK, который пытается применять следующие методы аутентификации по порядку:

переменные среды
Идентификация рабочей нагрузки для Kubernetes.
Управляемая идентификация.
Учетные данные Azure CLI.
Учетные данные Azure PowerShell.
Учетные данные Azure Developer CLI.
Интерактивный браузер, если включен.

Пример: Аутентификация по умолчанию

Следующий пример подключается к ActiveDirectoryDefault, используя цепочку DefaultAzureCredential для автоматического поиска действительных учетных данных:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

cursor = conn.cursor()
cursor.execute("SELECT USER_NAME()")
print(f"Connected as: {cursor.fetchval()}")

Используйте этот режим для локальной разработки, так как он автоматически получает учетные данные Azure CLI. Для производства используйте специальный режим аутентификации (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) вместо этого. DefaultAzureCredential перебирает несколько поставщиков учетных данных при каждом первом подключении, что вносит дополнительную задержку, не нужную для производственных рабочих нагрузок.

Интерактивная проверка подлинности

Для интерактивных приложений используйте аутентификацию на базе браузера. Пользователь должен иметь учётную запись базы данных, созданную с помощью CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Для полных требований см. раздел Configure Microsoft Entra authentication.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryInteractive;"
    "Encrypt=yes;"
)

В Windows этот режим использует собственный интерактивный процесс драйвера ODBC. На других платформах используется браузерная аутентификация Azure Identity SDK.

Проверка подлинности кода устройства

Используйте аутентификацию кода устройства для сред без браузера, таких как SSH-сессии или контейнеры. Пользователь должен иметь учётную запись базы данных, созданную с помощью CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Для предварительных требований см. раздел Configure Microsoft Entra authentication.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Output: To sign in, use a web browser to open https://microsoft.com/devicelogin
# and enter the code XXXXXXX to authenticate.

Следуйте запросу для аутентификации в браузере на другом устройстве.

Аутентификация сервисного принципала

Используйте аутентификацию принципа сервиса для автоматизированных приложений, не требующих взаимодействия пользователя:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"       # Application (client) ID
    "PWD=<client-secret>;"   # Client secret
    "Encrypt=yes;"
)

Создайте сервисного принципала

Зарегистрируйте приложение в Microsoft Entra ID.
Создайте секрет клиента.
Предоставьте принципалу сервиса доступ к вашей базе данных:

-- In Azure SQL
CREATE USER [app-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [app-name];
ALTER ROLE db_datawriter ADD MEMBER [app-name];

Tip

Если при выполнении CREATE USER возникает ошибка 33131 (дублирующееся отображаемое имя), используйте WITH OBJECT_ID, чтобы указать идентификатор объекта субъекта-службы на странице Корпоративные приложения в портале Azure (а не на странице регистрации приложения):

CREATE USER [app-name] FROM EXTERNAL PROVIDER
    WITH OBJECT_ID = '<enterprise-app-object-id>';

Подробнее см. Входы в Microsoft Entra и пользователи с неуникальными отображаемыми именами.

Манажируемая идентичность

Используйте управляемую аутентификацию идентичности для приложений, размещённых в Azure, таких как App Service, Функции Azure и VM:

Системно назначенная управляемая идентичность

Подключитесь с помощью идентификатора, напрямую присвоенного ресурсу Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes;"
)

Управляемая идентификация, назначаемая пользователем

Укажите идентификатор клиента управляемой идентификации, назначаемой пользователем, в поле UID:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "UID=<managed-identity-client-id>;"
    "Encrypt=yes;"
)

Настройка доступа к базе данных

Предоставьте управляемый доступ к идентификации в вашей базе данных. Администратор Microsoft Entra должен быть настроен на сервере, прежде чем вы сможете создавать внешних пользователей. Чтобы включить управляемую идентичность на вашем ресурсе Azure, см. раздел Managed identities for Azure resources.

-- Replace 'my-app-service' with your Azure resource name
CREATE USER [my-app-service] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-app-service];
ALTER ROLE db_datawriter ADD MEMBER [my-app-service];

Аутентификация пароля (устаревшая)

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. Пользователь должен иметь учётную запись базы данных, созданную с помощью CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryPassword;"
    "UID=<login@domain.com>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Интегрированная аутентификация Windows

Используйте интегрированную аутентификацию Windows для доменно-связанных сред Windows с помощью Kerberos. Этот режим требует, чтобы ваш локальный Active Directory был федеративен с помощью Microsoft Entra ID и настроенного администратора Microsoft Entra на сервере:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryIntegrated;"
    "Encrypt=yes;"
)

В этом режиме используются данные Kerberos текущего пользователя Windows. На Linux и macOS нужно настраивать Kerberos вручную (krb5.conf и использовать действительную вкладку или тикет). См. раздел «Использовать аутентификацию Active Directory с SQL Server на Linux» для настройки Kerberos на стороне клиента.

Проверка подлинности токена доступа

Вы можете получить токены снаружи, например, через пользовательского провайдера токенов или общий кэш токенов. В таких случаях используйте SQL_COPT_SS_ACCESS_TOKEN с параметром attrs_before для передачи токена напрямую. Этот подход обходит встроенный драйвером поток приобретения токенов.

import mssql_python
from azure.identity import DefaultAzureCredential
import struct

def get_token():
    credential = DefaultAzureCredential(
        exclude_interactive_browser_credential=False
    )
    token_bytes = credential.get_token(
        "https://database.windows.net/.default"
    ).token.encode("utf-16le")
    token_struct = struct.pack(
        f'<I{len(token_bytes)}s', len(token_bytes), token_bytes
    )
    return token_struct

SQL_COPT_SS_ACCESS_TOKEN = 1256

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;",
    attrs_before={SQL_COPT_SS_ACCESS_TOKEN: get_token()}
)

Important

При использовании SQL_COPT_SS_ACCESS_TOKEN, строка строка подключения не должна включать UID, PWD, Authentication, или Trusted_Connection. Сам токен занимается аутентификацией.

Выбор режима проверки подлинности

Сценарий	Рекомендуемый режим
Машина для разработки	`ActiveDirectoryDefault`(использует Azure CLI)
Служба приложений Azure / Функции	`ActiveDirectoryMSI` (быстрее, чем по умолчанию)
Служба Azure Kubernetes	`ActiveDirectoryDefault` (идентификация рабочей нагрузки)
Автоматизированные локальные скрипты	`ActiveDirectoryServicePrincipal`
Интерактивное десктопное приложение	`ActiveDirectoryInteractive`
SSH/контейнер без браузера	`ActiveDirectoryDeviceCode`

Troubleshoot

Проверьте, существует ли пользовательская или управляемая личность в базе данных:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Приложение не найдено"

Принципал сервиса или идентификатор приложения неверен. Проверьте идентификатор клиента и подтвердите, что приложение зарегистрировано в вашем арендаторе Microsoft Entra.

"Управляемая идентификационная конечная точка недоступна"

Проверьте, включена ли управляемая идентичность на ресурсе Azure.
Для идентификации, присвоенной пользователем, проверьте правильность идентификатора клиента.
Проверьте, есть ли у ресурса сетевой доступ к конечной точке идентичности.

Тайм-аут получения токена

ActiveDirectoryDefault Использует DefaultAzureCredential, который последовательно перемещается по цепочке поставщиков учётных данных, пока один не будет успешен. Эта цепная прогулка добавляет секунды задержки при первом соединении, особенно когда более ранние провайдеры в цепочке (переменные среды, идентификация рабочей нагрузки) выходят из строя до того, как достигнут работающего. В продакшене указывайте тип учетных данных напрямую, чтобы пропустить цепочку:

# Slow: DefaultAzureCredential tries multiple providers
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryDefault")

# Fast: Skip directly to managed identity
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryMSI")

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

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

Last updated on 2026-07-22