Microsoft Entra Authentifizierung mit mssql-django

In diesem Artikel wird erläutert, wie Sie Microsoft Entra Authentifizierung für Django-Anwendungen mithilfe des mssql-django Back-End konfigurieren. Microsoft Entra Authentifizierung beseitigt die Notwendigkeit, Kennwörter in Ihrer Anwendungskonfiguration zu speichern.

Voraussetzungen

• Microsoft ODBC-Treiber 18 für SQL Server (empfohlen). Alle Authentifizierungsmodi in diesem Artikel werden mit Microsoft ODBC-Treiber 18 für SQL Server unterstützt. ActiveDirectoryInteractive ist unabhängig von der Treiberversion nur für Windows verfügbar. Wenn Sie ODBC Driver 17 verwenden müssen, finden Sie in der ODBC-Authentifizierungsreferenz die je Modus erforderlichen Mindestversionen der Reihe 17.x.
• Für die Authentifizierung mit Zugriffstoken: pip install azure-identity.

Authentifizierungsmethoden

Konfigurieren Sie jede Methode, indem Sie die Einstellung in der DATABASES Datei Ihres Django-Projekts settings.py hinzufügen oder bearbeiten. Die Beispiele in diesem Artikel zeigen den vollständigen DATABASES["default"] Block zur Übersichtlichkeit; kopieren Sie die relevanten Schlüssel in Ihre vorhandene Konfiguration.

mssql-django unterstützt die Microsoft-Entra-Authentifizierung auf zwei Arten:

• ODBC-Treiberauthentifizierung über OPTIONS["extra_params"]. Das Back-End fügt diese Zeichenfolge an die ODBC-Verbindungszeichenfolge unverändert an, sodass die verfügbaren Authentication= Werte aus dem installierten Microsoft ODBC-Treiber für SQL Server stammen, nicht von mssql-django sich selbst.
• Programmgesteuerte Zugriffstokenauthentifizierung über die TOKEN Einstellung. Das Back-End übergibt TOKEN an den ODBC-Treiber als SQL_COPT_SS_ACCESS_TOKEN, der das ODBC-Schlüsselwort Authentication= umgeht.

Authentifizierungsmethoden auf einen Blick

Gewähren des Identitätszugriffs in Azure SQL

Erstellen Sie für die verwaltete Identitäts- oder Dienstprinzipalauthentifizierung einen Datenbankbenutzer, und gewähren Sie nur die Rollen, die Ihre Anwendung benötigt:

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

Die db_ddladmin festen Datenbankrolle ist nur erforderlich, wenn die Anwendung Migrationen ausführt. Bei schreibgeschützten Workloads ist db_datareader ausreichend.

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

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

Wenn ein VIEW ANY COLUMN MASTER KEY DEFINITION permission denied Fehler angezeigt wird, gewähren Sie der Identität zusätzlichen Zugriff für Always Encrypted-Szenarien:

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

Verwaltete Identitätsauthentifizierung (ActiveDirectoryMsi)

Verwenden Sie verwaltete Identität, wenn Ihre Django-App auf einem Azure-Dienst wie Azure App Service, Azure Container Apps oder Azure Virtual Machines ausgeführt wird. Dieser Ansatz wird für Produktionsumgebungen empfohlen, da der ODBC-Treiber Token automatisch erwirbt und aktualisiert.

Vom System zugewiesene verwaltete Identität:

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",
        },
    },
}

Vom Benutzer zugewiesene verwaltete Identität:

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 ist der ODBC-Modus sowohl für vom System zugewiesene verwaltete Identität (Managed Identity, SAMI) als auch für vom Benutzer zugewiesene verwaltete Identität (Managed Identity, UAMI). Für UAMI erwartet UID der ODBC-Treiber, die verwaltete Identität zu identifizieren: Verwenden Sie die Client-ID für Azure App Service oder Azure Containerinstanz, andernfalls verwenden Sie die Objekt-ID. Setzen Sie dies UID in extra_params, da extra_params direkt an den ODBC-Treiber übergeben wird.

Wenn Sie eine verwaltete Identität verwenden, erstellen Sie die Testdatenbank manuell und übergeben Sie --keepdb, wenn Sie Unit-Tests ausführen.

Dienstprinzipalauthentifizierung (ActiveDirectoryServicePrincipal)

Verwenden Sie eine Microsoft Entra App-Registrierung (Service Principal), wenn Ihre App ohne Benutzerkontext ausgeführt wird und keine verwaltete Identität verfügbar ist.

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",
        },
    },
}

Hartkodieren Sie keine Clientgeheimnisse in settings.py. Verwenden Sie Umgebungsvariablen oder einen geheimen Manager, z. B. Azure Key Vault, um Anmeldeinformationen zur Laufzeit bereitzustellen.

Integrierte Authentifizierung (ActiveDirectoryIntegrated)

Verwenden Sie die integrierte Authentifizierung, wenn der Django-Prozess unter einem in die Domäne eingebundenen Benutzerkontext ausgeführt wird und der ODBC-Treiber diese Windows oder Kerberos-Identität für Microsoft Entra Authentifizierung einlösen soll.

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",
        },
    },
}

Die ODBC-Authentifizierungsreferenz dokumentiert diesen Modus auf Windows und unter Linux oder macOS mit ODBC-Treiber 17.6 und höheren Versionen für Verbundumgebungen.

Interaktive Authentifizierung (ActiveDirectoryInteractive)

Verwenden Sie die interaktive Authentifizierung für die lokale Benutzeranmeldung, wenn der Treiber zur Eingabe von Anmeldeinformationen auffordern und die mehrstufige Authentifizierung behandeln soll.

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",
        },
    },
}

Die wichtigsten Referenzdokumente zur ODBC-Authentifizierung bezeichnen ActiveDirectoryInteractive als nur für Windows verfügbar. Wenn Sie beabsichtigen, es auf einer anderen Plattform zu verwenden, überprüfen Sie zuerst das Verhalten mit Ihrer genauen Treiberversion.

Authentifizierung mit der Standardanmeldeinformationskette (ActiveDirectoryDefault)

Verwenden Sie diesen Modus, wenn der ODBC-Treiber die Standard-Microsoft Entra Anmeldeinformationskette anwenden soll.

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 und höhere Versionen übergeben diesen Modus an den ODBC-Treiber. Wenn Sie explizite Kontrolle über das Verhalten der Anmeldeinformationsquelle oder des Tokenaktualisierungsverhaltens benötigen, verwenden Sie die Zugriffstokenauthentifizierung.

Zugriffstokenauthentifizierung (TOKEN)

Verwenden Sie TOKEN, wenn Ihr Python-Code das Microsoft Entra-Token selbst abrufen soll.

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",
        },
    },
}

Dieser Pfad funktioniert mit jeder Python Anmeldeinformationsklasse, einschließlich DefaultAzureCredential, ManagedIdentityCredentialund ClientSecretCredential.

Abgerufene settings.py Zugriffstoken werden beim Prozessstart einmal ausgewertet und laufen in der Regel nach 60 bis 90 Minuten ab. Wenn Ihr Django-Prozess länger als die Tokenlebensdauer bleibt, müssen Sie das Token im Anwendungscode aktualisieren. Verwenden Sie für die meisten langlebigen Produktionsanwendungen einen ODBC-Treibermodus, der Token automatisch aktualisiert, wie ActiveDirectoryMsi oder ActiveDirectoryServicePrincipal.

Kennwortauthentifizierung (ActiveDirectoryPassword, veraltet)

Microsoft Entra ID Kennwortauthentifizierung basiert auf der OAuth 2.0 Resource Owner Password Credentials (ROPC)-Erteilung, die es einer Anwendung ermöglicht, sich beim Benutzer direkt anzumelden, indem es sein Kennwort direkt verarbeitet.

Microsoft empfiehlt, den ROPC-Fluss nicht zu verwenden, da er nicht mit MFA kompatibel ist. In den meisten Szenarien sind sicherere Alternativen verfügbar und empfohlen. Dieser Fluss erfordert ein hohes Vertrauen in die Anwendung und trägt Risiken, die in anderen Flüssen nicht vorhanden sind. Verwenden Sie diesen Fluss nur, wenn sicherere Flüsse nicht lebensfähig sind. Microsoft entfernt sich von diesem Authentifizierungsfluss mit hohem Risiko, um Benutzer vor böswilligen Angriffen zu schützen. Weitere Informationen finden Sie unter Planung für die obligatorische mehrstufige Authentifizierung für Azure.

Wenn ein Benutzer bei der Anmeldung vorhanden ist, verwenden Sie die ActiveDirectoryInteractive- oder ActiveDirectoryIntegrated-Authentifizierung, sodass die Attribute des Überwachungspfads für den angemeldeten Benutzer und die Richtlinien für bedingten Zugriff gelten.

Befolgen Sie für unbeaufsichtigte Dienst-zu-Dienst-Szenarien die Microsoft Entra Richtlinien für das Dienstkonto:

• Wenn Ihre Anwendung in Azure Infrastruktur ausgeführt wird, verwenden Sie ActiveDirectoryMSI (oder ActiveDirectoryManagedIdentity in einigen Treibern). Verwaltete Identitäten beseitigen den Aufwand für die Verwaltung und Rotation von Geheimnissen und Zertifikaten.
• Wenn verwaltete Identität nicht verfügbar ist (z. B. wird die Anwendung außerhalb Azure ausgeführt), verwenden Sie ActiveDirectoryServicePrincipal. Wo der Treiber dies unterstützt, bevorzugen Sie ein Clientzertifikat über einen geheimen Clientschlüssel. Bei einem Zertifikat bleibt der private Schlüssel auf dem Client, und nur eine signierte Assertion wird an Microsoft Entra gesendet, um den Client zu authentifizieren. Wenn der Schlüssel in Hardware gespeichert ist (z. B. in einem TPM oder HSM) oder als nicht exportierbar gekennzeichnet ist, kann er nicht wie ein Clientgeheimnis als Zeichenfolge extrahiert werden.
• Verwenden Sie kein Microsoft Entra Benutzerkonto als Dienstkonto.

Wenn Sie es für ein Legacyszenario verwenden müssen, konfigurieren Sie es explizit:

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",
        },
    },
}

Verwandte Inhalte

• Bewährte Methoden für sicherheit für mssql-django
• mssql-django-Konfigurationsreferenz
• Verbindungsoptionen für mssql-django
• Bereitstellen einer Django-App mit SQL Server zum Azure App Service
• Verwenden von Microsoft Entra ID mit dem ODBC-Treiber
• Konfigurieren und Verwalten der Microsoft Entra-Authentifizierung mit Azure SQL
• Microsoft Entra-Authentifizierungswiki
• Immer verschlüsselt mit mssql-django