проверка подлинности Microsoft Entra с помощью mssql-django

В этой статье объясняется, как настроить аутентификацию Microsoft Entra для приложений Django с помощью backend-компонента mssql-django. Microsoft Entra проверка подлинности устраняет необходимость хранения паролей в конфигурации приложения.

Необходимые условия

Microsoft драйвер ODBC 18 для SQL Server (рекомендуется). Все режимы проверки подлинности в этой статье поддерживаются с Microsoft ODBC Driver 18 для SQL Server. ActiveDirectoryInteractiveдоступно только в Windows независимо от версии драйвера. Если необходимо использовать драйвер ODBC 17, см. справочник по аутентификации ODBC, чтобы узнать минимальные версии 17.x для каждого режима.
Для аутентификации с использованием токена доступа: pip install azure-identity

Методы аутентификации

Настройте каждый метод, добавив или изменив DATABASES параметр в файле проекта settings.py Django. В примерах этой статьи показан полный DATABASES["default"] блок для ясности. Скопируйте соответствующие ключи в существующую конфигурацию.

mssql-djangoподдерживает проверку подлинности Microsoft Entra двумя способами:

Проверка подлинности драйвера ODBC с помощью OPTIONS["extra_params"]. Серверная часть добавляет эту строку к строке подключения ODBC без изменений, поэтому доступные значения Authentication= берутся из установленного драйвера Microsoft ODBC Driver for SQL Server, а не из самого mssql-django.
Аутентификация токена программного доступа через параметр TOKEN. Серверная часть передаёт TOKEN драйверу ODBC как SQL_COPT_SS_ACCESS_TOKEN, что позволяет обойти ключевое слово ODBC Authentication=.

Методы проверки подлинности на первый взгляд

Метод	Настройка с помощью	лучше всего подходит для
токен доступа	`TOKEN`	Разработка, кратковременные скрипты или приложения с пользовательским обновлением токена
`ActiveDirectoryMsi`	`extra_params`	Рабочие приложения, размещенные в Azure (управляемая идентификация, назначаемая системой и пользователем)
`ActiveDirectoryServicePrincipal`	`USER`, `PASSWORD`, `extra_params`	Регистрации приложений, когда управляемое удостоверение недоступно
`ActiveDirectoryIntegrated`	`extra_params`	Контекст пользователя, присоединенного к домену
`ActiveDirectoryInteractive`	`USER`, `extra_params`	Вход пользователя с многофакторной проверкой подлинности (Windows)
`ActiveDirectoryDefault`	`extra_params`	Локальная разработка и приложения, которые должны использовать цепочку учетных данных Microsoft Entra, используемую драйвером ODBC по умолчанию
`ActiveDirectoryPassword`	`USER`, `PASSWORD`, `extra_params`	Только для устаревших сценариев на крайний случай (устарело)

Note

mssql-django версии 1.7.3 и более поздние поддерживают Authentication=ActiveDirectoryDefault–OPTIONS["extra_params"], если установленный драйвер Microsoft ODBC для SQL Server поддерживает этот режим. Если вам нужен явный контроль над поведением получения и обновления токена, используйте модель TOKEN с классом azure.identity.DefaultAzureCredential.

Предоставление доступа к удостоверениям в Azure SQL

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

CREATE USER [<identity-name>] FOR EXTERNAL PROVIDER;

ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<identity-name>];

Предопределённая роль базы данных db_ddladmin требуется только в том случае, если приложение выполняет миграции. Для нагрузок, предназначенных только для чтения, достаточно db_datareader.

Note

FROM EXTERNAL PROVIDERтребует, чтобы SQL Server вызывал Microsoft Graph для разрешения имени субъекта. Если сервер настроен для проверки подлинности только Microsoft Entra или не может достичь Graph, инструкция завершается ошибкой Msg 33130 (Principal '<name>' could not be found...). Создайте пользователя вручную, указав явный идентификатор безопасности:

CREATE USER [<identity-name>] WITH SID = 0x<sid-hex>, TYPE = E;

Для управляемого удостоверения или субъекта-службы получайте SID из идентификатора приложения (клиента) удостоверения, а не из его идентификатора объекта. Azure SQL использует идентификатор приложения для субъектов-служб и управляемых удостоверений, а идентификатор объекта — только для обычных пользователей Entra. Преобразуйте GUID, изменив порядок байтов в первых трёх группах, разделённых дефисами, на обратный, и оставив последние две без изменений. Например, идентификатор приложения 00001111-aaaa-2222-bbbb-3333cccc4444 становится SID 0x11110000AAAA2222BBBB3333CCCC4444. В PowerShell:

$b = ([Guid]"<app-id>").ToByteArray()
"0x" + (($b | ForEach-Object { $_.ToString('X2') }) -join '')

Если вы по ошибке используете идентификатор объекта, подключение успешно получает токен, но Azure SQL возвращает Login failed for user '<token-identified principal>', так как ни один принципал базы данных не соответствует утверждению appid в токене.

Если вы видите ошибку VIEW ANY COLUMN MASTER KEY DEFINITION permission denied, предоставьте этой идентификационной записи дополнительные права доступа для сценариев Always Encrypted:

GRANT VIEW ANY COLUMN MASTER KEY DEFINITION TO [<identity-name>];
GRANT VIEW ANY COLUMN ENCRYPTION KEY DEFINITION TO [<identity-name>];

Аутентификация с помощью управляемой идентификации (`ActiveDirectoryMsi`)

Используйте управляемое удостоверение, если приложение Django работает в службе Azure, например Служба приложений Azure, Контейнеры приложений Azure или Виртуальные машины Azure. Этот подход рекомендуется для рабочих сред, так как драйвер ODBC получает и обновляет маркеры автоматически.

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

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryMsi",
        },
    },
}

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

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": (
                "Authentication=ActiveDirectoryMsi;"
                "UID=<managed-identity-client-id-or-object-id>"
            ),
        },
    },
}

ActiveDirectoryMsi — это режим ODBC для управляемого удостоверения, назначаемого системой (SAMI), и управляемого удостоверения, назначаемого пользователем (UAMI). Для UAMI драйвер ODBC ожидает, что в UID будет указан идентификатор управляемого удостоверения: используйте идентификатор клиента для Служба приложений Azure или Azure Container Instance, в противном случае используйте идентификатор объекта. Поместите его UID внутрь extra_params, так как extra_params передается непосредственно драйверу ODBC.

Если вы используете управляемую идентификацию, создайте тестовую базу данных вручную и передайте --keepdb при запуске модульных тестов.

Аутентификация субъекта-службы (`ActiveDirectoryServicePrincipal`)

Используйте регистрацию приложения Microsoft Entra (субъект-службу), если приложение работает без контекста пользователя и управляемое удостоверение недоступно.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<application-client-id>",
        "PASSWORD": "<client-secret>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal",
        },
    },
}

Не прописывайте секреты клиента жестко в settings.py. Используйте переменные среды или диспетчер секретов, например Azure Key Vault, чтобы предоставить учетные данные во время выполнения.

Встроенная проверка подлинности (`ActiveDirectoryIntegrated`)

Используйте интегрированную аутентификацию, если процесс Django выполняется от имени пользователя домена и требуется, чтобы драйвер ODBC использовал эти учетные данные Windows или Kerberos для аутентификации в Microsoft Entra.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryIntegrated",
        },
    },
}

В справочнике по проверке подлинности ODBC описан этот режим для Windows, а также для Linux и macOS при использовании ODBC Driver 17.6 и более поздних версий в федеративных средах.

Интерактивная проверка подлинности (`ActiveDirectoryInteractive`)

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

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<user@email.com>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryInteractive",
        },
    },
}

В основных справочных документах ActiveDirectoryInteractive аутентификация ODBC указана как доступная только в Windows. Если вы планируете использовать его на другой платформе, сначала проверьте поведение с точной версией драйвера.

Аутентификация с помощью цепочки учетных данных по умолчанию (`ActiveDirectoryDefault`)

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

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryDefault",
        },
    },
}

mssql-django Версии 1.7.3 и более поздних версий передают этот режим драйверу ODBC. Если вам нужен явный контроль над источником учетных данных или поведением обновления токена, используйте аутентификацию с помощью токена доступа.

Аутентификация по токену доступа (`TOKEN`)

ИспользуйтеTOKEN, если требуется, чтобы код Python приобрел сам токен Microsoft Entra.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "TOKEN": token,
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Этот путь работает с любым классом учетных данных Python, включая DefaultAzureCredential, ManagedIdentityCredentialи ClientSecretCredential.

Токены доступа, полученные в settings.py, проверяются один раз при запуске процесса и обычно истекает срок их действия через 60–90 минут. Если ваш процесс Django продолжает работать дольше срока действия токена, необходимо обновить токен в коде приложения. Для большинства длительных рабочих приложений используйте режим драйвера ODBC, который автоматически обновляет маркеры, например ActiveDirectoryMsi или ActiveDirectoryServicePrincipal.

Проверка подлинности паролей (`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 учетную запись пользователя в качестве учетной записи службы.

Если его необходимо использовать для устаревшего сценария, настройте его явным образом:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<user@email.com>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryPassword",
        },
    },
}

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

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

Last updated on 2026-07-21

проверка подлинности Microsoft Entra с помощью mssql-django

Необходимые условия

Методы аутентификации

Методы проверки подлинности на первый взгляд

Предоставление доступа к удостоверениям в Azure SQL

Аутентификация с помощью управляемой идентификации (ActiveDirectoryMsi)

Аутентификация субъекта-службы (ActiveDirectoryServicePrincipal)

Встроенная проверка подлинности (ActiveDirectoryIntegrated)

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

Аутентификация с помощью цепочки учетных данных по умолчанию (ActiveDirectoryDefault)

Аутентификация по токену доступа (TOKEN)

Проверка подлинности паролей (ActiveDirectoryPasswordне рекомендуется)

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