Microsoft Entra-Authentifizierung mit Microsoft. Data.SqlClient

Gilt für: .NET Framework .NET .NET Standard

Herunterladen von ADO.NET

Verwenden Sie Microsoft Entra ID, um sich zu verbinden, ohne ein SQL-Passwort in Ihrer Anwendung zu speichern. Wählen Sie eine Anmeldemethode für den Host, auf dem die Anwendung läuft, stellen Sie diese Identität in der Zieldatenbank bereit und lassen Sie die Transport Layer Security (TLS)-Zertifikatsvalidierung aktiviert.

Übersicht

Die vom Treiber bereitgestellten Active Directory ... Authentifizierungsmodi erfordern sowohl Microsoft.Data.SqlClient als auch Microsoft.Data.SqlClient.Extensions.Azure. Installieren Sie passende Versionen:

dotnet add package Microsoft.Data.SqlClient --version 7.1.0
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.0

Die Erweiterung registriert ihre Anbieter automatisch. Anwendungen, die ihren eigenen AccessToken, AccessTokenCallback, oder Authentifizierungsanbieter bereitstellen, benötigen die Azure-Erweiterung nicht ausschließlich für diesen Zweck. Füge die Identitätsbibliothek hinzu, die dein eigener Token-Code verwendet.

Vor der Verbindung:

1. Konfigurieren Sie die Microsoft Entra-Authentifizierung für Azure SQL oder folgen Sie der entsprechenden Konfiguration Ihres Zieldienstes.
2. Gewähren Sie der Anwendung oder der Benutzeridentität Zugriff auf die vorgesehene Datenbank. Das Erhalten eines Tokens gewährt keine Datenbankberechtigungen.
3. Erlauben Sie Netzwerkzugriff zum Endpunkt und wählen Sie die Datenbank explizit aus.
4. Wählen Sie einen unterstützten Authentifizierungsmodus und stellen Sie dessen Zugangsdaten auf dem Anwendungshost bereit.

Die SQL-Datenbank in Microsoft Fabric unterstützt ausschließlich Microsoft Entra-Authentifizierung. Es unterstützt keine SQL-Authentifizierung oder SQL-Logins. Verwenden Sie den Verbindungszeichenfolge aus dem Fabric-Portal für den vorgesehenen Endpunkt.

Auswählen eines Authentifizierungsmodus

Setze Authentication auf einen der Verbindungsstring-Werte in dieser Tabelle. Die Release-Spalte hilft dir, von älteren Treibern zu migrieren. Aktuelle Anwendungen sollten die in der Übersicht beschriebenen Pakete installieren.

Authentication=Sql Passwordist SQL-Authentifizierung, nicht Microsoft Entra-Authentifizierung. Siehe SQL Server und Windows-Authentifizierung.

Eröffne eine Verbindung

Legen Sie für eine .NET-Konsolenanwendung SQL_CONNECTION_STRING auf die entsprechende Vorlage aus diesem Artikel fest, nachdem Sie die Platzhalter ersetzt haben. Dieses Beispiel öffnet die Verbindung und druckt den Datenbanknamen:

using Microsoft.Data.SqlClient;

string connectionString = Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException("Set SQL_CONNECTION_STRING before running.");

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());

Jeder Modus hat unterschiedliche Voraussetzungen für den Gastgeber. Eine vom Parser akzeptierte Verbindungszeichenfolge beweist nicht, dass der Host ein Token erhalten kann oder dass die Identität auf die Datenbank zugreifen kann.

Verwenden Sie integrierte Authentifizierung

Active Directory Integrated erwirbt ein Microsoft Entra-Token, indem es die angemeldete Domain-Identität verwendet. Es erfordert die entsprechende Konfiguration der verbundenen oder föderierten Identität. Es ist nicht dasselbe wie Integrated Security=true, das Windows Authentication direkt mit SQL Server verwendet.

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Integrated;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Gib weder ein Passwort noch SqlCredential ein. Ein Benutzername-Hinweis ist in modernen .NET optional; .NET Framework akzeptiert für diesen Modus keinen Benutzernamen. Die IWA kann eine interaktive MFA-Herausforderung nicht erfüllen. Verwenden Sie interaktive Authentifizierung, wenn der Mieter eine Benutzerinteraktion benötigt.

Verwenden der interaktiven Authentifizierung

Verwenden Sie Active Directory Interactive für eine Person, die sich bei einer Desktop- oder Entwickleranwendung anmeldet. Der Authentifizierungsanbieter fordert den Benutzer auf und unterstützt MFA. Eine optionale User ID=<user_id> Variante bietet einen Anmeldehinweis, kein Passwort.

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Geben Sie Password oder SqlCredential nicht an. Nutzen Sie keinen interaktiven Modus für einen unbeaufsichtigten Dienst.

Verwenden Sie die Dienstprinzipalauthentifizierung

Der integrierte Active Directory Service Principal-Modus verwendet die Client-ID einer Anwendung als User ID und ihr Clientgeheimnis als Password. Stellen Sie den Service Principal in der Datenbank bereit und gewähren Sie nur die benötigten Berechtigungen.

Holen Sie das Geheimnis aus der geschützten Konfiguration ab, anstatt es in die Quellcode einzubetten. Dieses Konsolenbeispiel liest Werte aus, die in den Prozess eingeschleust wurden:

using Microsoft.Data.SqlClient;

static string Required(string name) =>
    Environment.GetEnvironmentVariable(name)
    ?? throw new InvalidOperationException($"Set {name} before running.");

var options = new SqlConnectionStringBuilder
{
    DataSource = Required("SQL_SERVER"),
    InitialCatalog = Required("SQL_DATABASE"),
    Authentication = SqlAuthenticationMethod.ActiveDirectoryServicePrincipal,
    UserID = Required("AZURE_CLIENT_ID"),
    Password = Required("AZURE_CLIENT_SECRET"),
    Encrypt = SqlConnectionEncryptOption.Mandatory,
    TrustServerCertificate = false,
    MultiSubnetFailover = true
};

using var connection = new SqlConnection(options.ConnectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());

Setzen Sie SQL_SERVER auf Ihren Transmission-Control-Protocol-(TCP)-Endpunkt, wie z. B. tcp:contoso.database.windows.net,1433, und SQL_DATABASE auf den Datenbanknamen. Protokolliere nicht die Umgebungswerte oder den Verbindungszeichenfolge.

Für zertifikatsbasierte Anwendungsanmeldeinformationen fordern Sie Token mit ClientCertificateCredential über AccessTokenCallback an. Für föderierte Zugangsdaten verwenden Sie Workload-Identität oder einen geeigneten Token-Callback. Der Dienstprinzipalmodus für Verbindungszeichenfolgen selbst erfordert ein Clientgeheimnis.

Verwenden Sie die Authentifizierung per Gerätecodefluss

Nutzen Sie diesen Modus, wenn der Anwendungshost keinen Browser hat, aber eine Person sich auf einem anderen Gerät anmelden kann. Folgen Sie der vom Authentifizierungsprozess bereitgestellten Verifizierungs-URL und Code.

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Device Code Flow;Connect Timeout=180;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Connect Timeout Grenzauthentifizierung; dieses Beispiel erlaubt 180 Sekunden. Geben Sie User ID, Password oder SqlCredential nicht an. Der Codefluss des Geräts erfordert weiterhin eine Person und ist für unbeaufsichtigte Dienste ungeeignet.

Verwenden von Authentifizierung der verwalteten Identität

Für eine von Azure gehostete Anwendung verwenden Sie eine verwaltete Identität, wenn der Host sie unterstützt. Die Identität gehört zum Anwendungshost, nicht automatisch zum Datenbankserver.

• Eine vom System zugewiesene verwaltete Identität teilt den Lebenszyklus der Hostressource.
• Eine benutzerdefinierte verwaltete Identität ist eine separate Ressource, die Sie unterstützten Hosts zuweisen können.

Für eine vom System zugewiesene Identität lassen Sie User ID weg:

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Für eine vom Benutzer zugewiesene Identität geben Sie deren Client-ID an:

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;User ID=<client_id>;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Active Directory MSI ist eine Kompatibilitätsschreibweise für denselben Modus. Geben Sie kein Passwort oder SqlCredential an. Der Host muss die ausgewählte verwaltete Identität offenlegen, und diese Identität muss Datenbankzugriff haben. Eine Entwicklerarbeitsstation erhält durch die Verwendung dieser Verbindungszeichenfolge keine verwaltete Identität.

Beim Migrieren von SqlClient 2.1 ersetzen Sie die vom Benutzer zugewiesene Objekt-ID durch deren Client-ID. SqlClient verwendet die Client-ID ab 3.0.

Verwenden Sie die Standard-Authentifizierung

Active Directory Defaultverwendet eine Azure Identity-Credential-Kette, um eine verfügbare Identität zu entdecken:

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Kandidaten hängen von der installierten Azure Identity-Version und -Konfiguration ab. Dazu gehören Umgebungszugangsdaten, Workload-Identität, verwaltete Identität und angemeldete Entwicklungstools wie Visual Studio, Azure Command-Line Interface (CLI), Azure PowerShell und Azure Developer CLI. Siehe DefaultAzureCredential für die aktuelle Kette.

SqlClient deaktiviert InteractiveBrowserCredential in diesem Modus. Wähle Active Directory Interactive , ob die Anwendung selbst die Anmeldung auffordern muss. Eine Entwicklungstool-Credential kann eine Sitzung verwenden, die durch eine frühere interaktive Anmeldung eingerichtet wurde.

Mit Active Directory Default kann sich die ausgewählte Identität ändern, wenn sich die Host-Konfiguration ändert.

Für ältere Bereitstellungen wurden die Workload-Identität in dieser Kette und die Unterstützung für die Azure Developer CLI mit SqlClient 5.1.4 eingeführt. Diese Funktion unterscheidet sich vom dedizierten Active Directory Workload Identity Modus, der in 5.2 eingeführt wurde. Azure PowerShell-Unterstützung kam in 5.0.

Verwenden Sie die Workload-Identitätsauthentifizierung

Verwenden Sie Active Directory Workload Identity auf einem Host, der für föderierte Workload-Identität konfiguriert ist. Der Identitätsanbieter muss dem Emittenten und dem Subjekt des projizierten Tokens vertrauen.

Das Zertifikat lautet:

• AZURE_TENANT_ID: die Mieter-ID.
• AZURE_CLIENT_ID: die Anwendungs- oder benutzerseitig zugewiesene Client-ID der verwalteten Identität.
• AZURE_FEDERATED_TOKEN_FILE: der Pfad zur projizierten Tokendatei.

Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Workload Identity;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Ein optionales User ID=<client_id> setzt die Client-ID außer Kraft. Die Verbindungszeichenfolge überschreibt weder die Tenant-ID noch den Pfad der Token-Datei. Fügen Sie den Inhalt der Token-Datei nicht in den Verbindungszeichenfolge oder in die Logs ein.

Ersetzen Sie die veraltete Passwortauthentifizierung

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.

Active Directory Password verwendet den Resource Owner Password Credentials-Flow und kann die MFA-Anforderungen nicht erfüllen. Das entsprechende SqlAuthenticationMethod.ActiveDirectoryPassword Enum-Element ist veraltet. Wählen Sie interaktive Authentifizierung für Nutzer oder verwaltete Identität, Arbeitslast-Identität oder eine Anwendungsberechtigung für Dienste.

Anpassen Sie die Microsoft Entra-Authentifizierung

Wählen Sie die kleinste Anpassung, die Ihren Anforderungen entspricht, aus den folgenden Anwendungsprogrammierschnittstellen (APIs):

Mit einem benutzerdefinierten ActiveDirectoryAuthenticationProviderFormular können Sie eine Client-ID der Anwendung bereitstellen, Gerätecode- oder Autorisierungscode-Rückrufe konfigurieren und das Elternfenster für interaktive Anmeldung einstellen, wo dies unterstützt wird. Verwenden Sie die API-Referenz des Anbieters für die Signaturen des installierten Erweiterungspakets.

Stellen Sie direkt einen Zugangstoken bereit

Legen Sie SqlConnection.AccessToken fest, bevor Sie die Verbindung öffnen. Der Kerntreiber unterstützt diese Eigenschaft ohne die Azure-Erweiterung.

Der literale Token ist Teil des Verbindungspool-Schlüssels. Ein anderer Token erzeugt einen anderen Pool. SqlClient erhält keine Ablaufzeit über diese Eigenschaft und kann das Token nicht für dich verlängern. Beschaffen Sie ein gültiges Token für neue Verbindungen und leeren Sie betroffene Pools, wenn Tokens ablaufen, insbesondere wenn Sie für Min Pool Size einen Wert ungleich null festgelegt haben.

Kombinieren Sie AccessToken nicht mit Authentication, integrierter Sicherheit, User ID oder Password, SqlCredential, AccessTokenCallback oder SspiContextProvider. Trage niemals einen Token ein.

Verwenden Sie AccessTokenCallback

Verwenden Sie AccessTokenCallback vorzugsweise, wenn Ihre Anwendung selbst Token abruft und Verbindungspooling verwendet. Der Rückruf liefert ein Token und dessen Verfallszeit zurück, sodass SqlClient eine Verlängerung für die pooled Authentication anfordern kann. Die API ist ab SqlClient 5.2 verfügbar.

Verwenden Sie dieselbe Delegierteninstanz und dieselbe Zugangsdaten für Verbindungen, die sich einen Pool teilen sollten. Der Callback-Delegate ist Teil des Pool-Schlüssels. Das Erstellen einer neuen Closure für jede Verbindung kann dazu führen, dass für jede Verbindung ein separater Pool erstellt wird.

Dieses .NET-Konsolenbeispiel verwendet die angemeldete Azure CLI-Identität für die lokale Entwicklung. Installieren Sie Microsoft.Data.SqlClient und Azure.Identity, melden Sie sich bei Azure CLI mit einer Identität an, die über Datenbankzugriff verfügt, und setzen Sie SQL_SERVER und SQL_DATABASE. Die Azure-Erweiterung ist für dieses Beispiel nicht erforderlich.

using Azure.Core;
using Azure.Identity;
using Microsoft.Data.SqlClient;

internal static class Program
{
    private static readonly TokenCredential Credential = new AzureCliCredential();

    private static readonly Func<SqlAuthenticationParameters, CancellationToken,
        Task<SqlAuthenticationToken>> TokenCallback = async (parameters, cancellationToken) =>
    {
        string scope = parameters.Resource.EndsWith("/.default", StringComparison.Ordinal)
            ? parameters.Resource
            : parameters.Resource + "/.default";
        AccessToken token = await Credential.GetTokenAsync(
            new TokenRequestContext(new[] { scope }), cancellationToken);
        return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
    };

    private static async Task Main()
    {
        var options = new SqlConnectionStringBuilder
        {
            DataSource = Required("SQL_SERVER"),
            InitialCatalog = Required("SQL_DATABASE"),
            Encrypt = SqlConnectionEncryptOption.Mandatory,
            TrustServerCertificate = false,
            MultiSubnetFailover = true
        };

        using var connection = new SqlConnection(options.ConnectionString)
        {
            AccessTokenCallback = TokenCallback
        };
        await connection.OpenAsync();
        using var command = new SqlCommand("SELECT DB_NAME();", connection);
        Console.WriteLine(await command.ExecuteScalarAsync());
    }

    private static string Required(string name) =>
        Environment.GetEnvironmentVariable(name)
        ?? throw new InvalidOperationException($"Set {name} before running.");
}

Ersetzen Sie für den Produktiveinsatz AzureCliCredential durch die vorgesehene Anmeldeinformation, z. B. ManagedIdentityCredential, WorkloadIdentityCredential oder ClientCertificateCredential, und konfigurieren Sie die entsprechenden Voraussetzungen. Ändern Sie nicht die Identität hinter einem gemeinsamen Rückruf, solange die gebündelten Verbindungen weiterhin verfügbar sind.

AccessTokenCallback nicht mit Authentication, integrierter Sicherheit, AccessToken oder SspiContextProvider kombinieren. Ein Callback kann User ID als Identitätsselektor verwenden, aber Ihr Callback muss User ID konsistent interpretieren. Das Beispiel verwendet keinen Selektor, weil es eine feste Zugangsberechtigung hat.

Unterstützung eines benutzerdefinierten SQL-Authentifizierungsanbieters

Leiten Sie von SqlAuthenticationProvider ab, implementieren Sie seinen Vertrag für die Tokenbeschaffung und registrieren Sie es bei SqlAuthenticationProvider.SetProvider für die Authentifizierungsmethode, die Sie ersetzen. Registrieren Sie Anbieter während der Anwendungsinitialisierung, bevor Sie Verbindungen öffnen.

Der Anbieter muss ein gültiges Token und eine Ablaufzeit für die angeforderte Ressource und Autorität zurückgeben. Die gleiche Sicherheitskontextregel, die für Rückrufe verwendet wird, gilt für Anbieter. Das Überschreiben eines Anbieters entfernt nicht die Anforderungen des Zieldiensts an Identität, Mandant oder Datenbankberechtigungen.

Migrieren zu Microsoft.Data.SqlClient 7.0

Anwendungen, die über die Paketaufteilung hinweg upgraden, sollten Abhängigkeiten und Authentifizierungskonfigurationen überprüfen.

Was sich in 7.0 geändert hat

Der Kerntreiber bringt keine Azure- und Microsoft Entra-Authentifizierungsabhängigkeiten mehr mit. Das integrierte ActiveDirectoryAuthenticationProvider wird nach Microsoft.Data.SqlClient.Extensions.Azure verschoben, mit gemeinsamen Verträgen in Microsoft.Data.SqlClient.Extensions.Abstractions.

Schritt 1: Installieren des Azure-Erweiterungspakets

Für von Treibern bereitgestellte Microsoft Entra-Modi installieren Sie passende Core- und Azure-Erweiterungsversionen, wie in der Übersicht gezeigt. Bereite die Erweiterung zusammen mit der Anwendung aus. Für die integrierten Modi ist keine manuelle Anbieterregistrierung erforderlich.

Schritt 2: Ersetzen veralteter Authentifizierungsmodi

Ersetzen Sie Active Directory Password sie durch einen Modus, der zum Benutzerinteraktions- und Hosting-Modell Ihrer Anwendung passt. Für eine unbeaufsichtigte Bereitstellung wählen Sie eine bestimmte Workload-Identität aus, anstatt sich auf die Anmeldung eines Entwicklers zu verlassen.

Schritt 3: Überprüfen von Verbindungszeichenfolgen

Behalte den bestehenden unterstützten Authentication Wert, falls er noch zur Bereitstellung passt. Bestätigen Sie den Datenbanknamen, die Identitätsauswahl, die Verschlüsselungseinstellungen und den Netzwerkzugang. Fügen Sie Integrated Security=true keiner Microsoft Entra-Verbindungszeichenfolge hinzu.

Anwendungen, die die Entra-ID-Authentifizierung nicht verwenden

SQL-Passwort und integrierte Windows-Authentifizierung erfordern keine Azure-Erweiterung. Anwendungen, die bereits eigene Token beziehen, können mit dem Kerntreiber und der gewählten Identitätsbibliothek weiterhin AccessToken oder AccessTokenCallback nutzen.

Verwandte Inhalte

• Microsoft Entra-Authentifizierung mit Azure SQL
• Anwendungs- und Dienstprinzipalobjekte in Azure Active Directory (Azure AD)
• SQL Server-Verbindungspooling
• Bewährte Methoden für Sicherheit