Microsoft Entra-Authentifizierung mit mssql-python

Microsoft Entra ID bietet identitätsbasierte Authentifizierung für Azure SQL-Datenbank, Azure SQL Managed Instance und SQL-Datenbank in Microsoft Fabric über den mssql-python-Treiber. Die Microsoft Entra-Authentifizierung bietet folgende Funktionen über die SQL-Authentifizierung:

• Zentralisiertes Identitätsmanagement über Microsoft Entra ID.
• Tokenbasierte Authentifizierung, die Passwörter überflüssig macht.
• Unterstützung für Richtlinien für bedingten Zugriff.
• Verwaltete Identitäten für von Azure gehostete Anwendungen.

Der mssql-python-Treiber unterstützt sieben Microsoft Entra-Authentifizierungsmodi, die alle über das Authentication Schlüsselwort Verbindungszeichenfolge konfiguriert sind.

Authentifizierungsmodi

Setzen Sie das Authentication Schlüsselwort in Ihrer Verbindungszeichenfolge auf einen der folgenden Werte:

DefaultAzureCredential

Der Modus ActiveDirectoryDefault verwendet DefaultAzureCredential aus dem Azure Identity SDK, das diese Authentifizierungsmethoden in der folgenden Reihenfolge versucht:

1. Umgebungsvariablen.
2. Workload-Identität für Kubernetes.
3. Verwaltete Identität.
4. Azure CLI-Anmeldeinformationen
5. Azure PowerShell-Anmeldeinformationen.
6. Azure Developer CLI-Zugangsdaten.
7. Interaktiver Browser, falls aktiviert.

Beispiel: Standard-Authentifizierung

Das folgende Beispiel verbindet sich mit ActiveDirectoryDefault, das die Kette DefaultAzureCredential nutzt, um automatisch eine gültige Zugangsdaten zu finden:

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()}")

Nutze diesen Modus für die lokale Entwicklung, da er automatisch Azure CLI-Zugangsdaten erkennt. Für die Produktion verwenden Sie stattdessen einen speziellen Authentifizierungsmodus (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal), DefaultAzureCredential geht bei jeder ersten Verbindung durch mehrere Zugangsdatenanbieter, was eine Latenz erhöht, die Produktionsworkloads nicht benötigen.

Interaktive Authentifizierung

Für interaktive Anwendungen verwenden Sie browserbasierte Authentifizierung. Der Benutzer muss ein Datenbankkonto mit CREATE USER [user@domain.com] FROM EXTERNAL PROVIDERerstellt haben. Für vollständige Voraussetzungen siehe Microsoft Entra-Authentifizierung konfigurieren.

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

Unter Windows delegiert dieser Modus dem nativen interaktiven Flow des ODBC-Treibers. Auf anderen Plattformen verwendet es die browserbasierte Authentifizierung des Azure Identity SDK.

Gerätecodeauthentifizierung

Verwenden Sie Gerätecode-Authentifizierung für Umgebungen ohne Browser, wie z. B. SSH-Sitzungen oder Container. Der Benutzer muss ein Datenbankkonto mit CREATE USER [user@domain.com] FROM EXTERNAL PROVIDERerstellt haben. Für Voraussetzungen siehe Konfigurieren der Microsoft Entra-Authentifizierung.

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.

Folgen Sie der Aufforderung, sich in einem Browser auf einem anderen Gerät zu authentifizieren.

Authentifizierung eines Service Principals

Verwenden Sie die Service Principal-Authentifizierung für automatisierte Anwendungen, die keine Benutzerinteraktion erfordern:

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

Erstellen eines Serviceprincipals

1. Registrieren Sie eine Anwendung in Microsoft Entra ID.
2. Erstellen Sie einen geheimen Clientschlüssel.
3. Gewähren Sie dem Dienstleiter Zugriff auf Ihre Datenbank:

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

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

Verwaltete Identität

Verwenden Sie Managed Identity Authentication für Azure-gehostete Anwendungen wie App Service, Azure Functions und VMs:

Vom System zugewiesene verwaltete Identität

Stellen Sie eine Verbindung mit der Identität her, die direkt der Azure-Ressource zugewiesen ist:

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

Vom Benutzer zugewiesene verwaltete Identität

Geben Sie die Client-ID einer benutzerdefinierten verwalteten Identität im Feld UID an:

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

Datenbankzugriff konfigurieren

Gewähren Sie den Zugriff auf die verwaltete Identität in Ihrer Datenbank. Ein Microsoft Entra-Administrator muss auf dem Server konfiguriert sein, bevor Sie externe Benutzer erstellen können. Um verwaltete Identität auf Ihrer Azure-Ressource zu aktivieren, siehe 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];

Passwortauthentifizierung (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.

Verwenden Sie Passwortauthentifizierung, wenn Sie einen Benutzernamen und ein Passwort mit einem Microsoft Entra-Konto benötigen. Der Benutzer muss über ein Datenbankkonto verfügen, das mit CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER erstellt wurde:

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

Windows Integrierte Authentifizierung

Verwenden Sie Windows Integrated Authentication für domänengebundene Windows-Umgebungen mit Kerberos. Dieser Modus erfordert, dass Ihr lokales Active Directory mit Microsoft Entra ID und einem auf dem Server konfigurierten Microsoft Entra-Administrator föderiert wird:

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

Dieser Modus verwendet die Kerberos-Zugangsdaten des aktuellen Windows-Nutzers. Unter Linux und macOS musst du Kerberos manuell konfigurieren (krb5.conf und ein gültiges Keytab oder Ticket). Siehe Verwenden der Active Directory-Authentifizierung mit SQL Server unter Linux für die Einrichtung von Kerberos auf dem Client.

Zugriffstokenauthentifizierung

Sie könnten Token extern erwerben, zum Beispiel über einen eigenen Token-Anbieter oder einen gemeinsamen Token-Cache. Verwenden Sie in diesen Fällen SQL_COPT_SS_ACCESS_TOKEN mit dem Parameter attrs_before, um das Token direkt zu übergeben. Dieser Ansatz umgeht den eingebauten Token-Akquisitionsfluss des Fahrers.

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()}
)

Auswählen eines Authentifizierungsmodus

Troubleshoot

„Anmeldung für Benutzer 'NT AUTHORITY\ANONYMOUS LOGON' fehlgeschlagen“

Überprüfen Sie, ob der Benutzer oder die verwaltete Identität in der Datenbank existiert:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Antrag nicht gefunden"

Die Service-Principal- oder Anwendungs-ID ist falsch. Überprüfen Sie die Client-ID und dass die App in Ihrem Microsoft Entra-Tenant registriert ist.

"Managed Identity-Endpunkt nicht erreichbar"

• Überprüfen Sie, dass die verwaltete Identität auf der Azure-Ressource aktiviert ist.
• Für benutzerdefinierte Identität überprüfen Sie, ob die Client-ID korrekt ist.
• Überprüfen Sie, ob die Ressource Netzwerkzugriff auf den Identity-Endpunkt hat.

Token-Erwerbszeitzeit

ActiveDirectoryDefault verwendet DefaultAzureCredential, das eine Kette von Anmeldeinformationsanbietern der Reihe nach durchläuft, bis einer davon erfolgreich ist. Diese Kettenwanderung fügt bei der ersten Verbindung Sekunden Latenz hinzu, besonders wenn frühere Anbieter in der Kette (Umgebungsvariablen, Arbeitslast-Identität) ausfallen, bevor sie die funktionierende Verbindung erreichen. In der Produktion geben Sie den Credential-Typ direkt an, um die Kette zu überspringen:

# 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")

Verwandte Inhalte

• Verbindungszeichenfolgen
• Problembehandlung
• Azure SQL kennwortlose Migration
• Microsoft Entra-Authentifizierung mit Azure SQL