Freigeben über

Herstellen einer Verbindung mit Azure SQL mit Microsoft Entra-Authentifizierung und SqlClient

  • Artikel

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

Herunterladen von ADO.NET

In diesem Artikel wird beschrieben, wie eine Verbindung mit Azure SQL-Datenquellen hergestellt werden kann, indem die Microsoft Entra-Authentifizierung (Azure AD) von einer .NET-Anwendung mit SqlClient verwendet wird.

Hinweis

Während Microsoft Entra-ID der neue Name für Azure Active Directory (Azure AD) ist, bleibt Azure AD in einigen fest kodierten Elementen wie Benutzeroberfläche-Feldern, Verbindungsanbietern, Fehlercodes und Cmdlets erhalten, um Störungen in bestehenden Umgebungen zu vermeiden. In diesem Artikel sind die beiden Namen austauschbar.

Übersicht

Die Microsoft Entra-Authentifizierung nutzt Identitäten in Microsoft Entra ID für den Zugriff auf Datenquellen wie Azure SQL-Datenbank, Azure SQL Managed Instance und Azure Synapse Analytics. Der Namespace Microsoft.Data.SqlClient ermöglicht es Clientanwendungen, Microsoft Entra-Anmeldedaten in verschiedenen Authentifizierungsmodi anzugeben, wenn sie eine Verbindung mit Azure SQL-Datenbank und Azure SQL Managed Instance herstellen. Um die Microsoft Entra-Authentifizierung mit Azure SQL zu verwenden, müssen Sie die Microsoft Entra-Authentifizierung mit Azure SQL konfigurieren und verwalten.

Wenn Sie die Verbindungseigenschaft Authentication in der Verbindungszeichenfolge festlegen, kann der Client entsprechend dem angegebenen Wert einen bevorzugten Microsoft Entra-Authentifizierungsmodus wählen:

  • Die früheste Version von Microsoft.Data.SqlClient unterstützt für .NET Framework, .NET Core und .NET Standard Active Directory Password. Außerdem werden für .NET Framework unterstützt die Authentifizierungstypen Active Directory Integrated und Active Directory Interactive.

  • Ab Microsoft.Data.SqlClient 2.0.0 wird die Unterstützung der Authentifizierungstypen Active Directory Integrated und Active Directory Interactive auf .NET Framework, .NET Core und .NET Standard ausgedehnt.

    SqlClient 2.0.0 bietet nun auch den neuen Authentifizierungsmodus Active Directory Service Principal. Dieser nutzt zur Authentifizierung die Client-ID und das Geheimnis einer Dienstprinzipalidentität.

  • Microsoft.Data.SqlClient 2.1.0 bietet weitere Authentifizierungsmodi, einschließlich Active Directory Device Code Flow und Active Directory Managed Identity (auch Active Directory MSI genannt). Diese neuen Modi ermöglichen der Anwendung das Abrufen eines Zugriffstokens, um eine Verbindung mit dem Server herzustellen.

Informationen zur Microsoft Entra-Authentifizierung, die über die Beschreibungen in den folgenden Abschnitten hinausgehen, finden Sie unter Verwenden der Microsoft Entra-Authentifizierung.

Einrichtung der Microsoft Entra-Authentifizierung

Wenn die Anwendung eine Verbindung mit Azure SQL-Datenquellen unter Verwendung der Microsoft Entra-Authentifizierung herstellt, muss sie einen gültigen Authentifizierungsmodus bieten. In der folgenden Tabelle sind die unterstützten Authentifizierungsmodi aufgeführt. Die Anwendung gibt einen Modus mithilfe der Verbindungseigenschaft Authentication in der Verbindungszeichenfolge an.

Wert BESCHREIBUNG Version von Microsoft.Data.SqlClient
Active Directory Password Authentifizieren mit dem Benutzernamen und Kennwort einer Microsoft Entra-Identität Ab 1.0
Active Directory Integrated Authentifizierung mit einer Microsoft Entra-Identität unter Verwendung der integrierten Windows-Authentifizierung (IWA) Ab 2.0.01
Active Directory Interactive Authentifizierung mit einer Microsoft Entra-Identität unter Verwendung der interaktiven Authentifizierung Ab 2.0.01
Active Directory Service Principal Authentifizieren mit einem Microsoft Entra-Dienstprinzipal mithilfe der Client-ID und des geheimen Schlüssels Ab 2.0.0
Active Directory Device Code Flow Authentifizierung mit einer Microsoft Entra-Identität unter Verwendung des Modus Gerätecodeflow Ab 2.1.0
Active Directory Managed Identity,
Active Directory MSI		 Authentifizierung mit einer systemseitig oder benutzerseitig zugewiesenen verwalteten Microsoft Entra-Identität. Ab 2.1.0
Active Directory Default Authentifizierung mit einer Microsoft Entra-Identität unter Verwendung von kennwortlosen und nicht interaktiven Mechanismen wie mit verwalteten Identitäten, Visual Studio Code, Visual Studio, der Azure CLI usw. 3.0.0 und höher
Active Directory-Workloadidentität Authentifizieren Sie sich mit einer Microsoft Entra-Identität mithilfe einer vom Verbund benutzerseitig zugewiesenen verwalteten Identität, um eine Verbindung mit SQL-Datenbank aus Azure-Clientumgebungen herzustellen, die für Workload Identity aktiviert sind. 5.2.0+

1 Vor Microsoft.Data.SqlClient 2.0.0 wurden die Authentifizierungsmodi Active Directory Integrated und Active Directory Interactive nur für .NET Framework unterstützt.

Verwendung der Kennwortauthentifizierung

Der Authentifizierungsmodus Active Directory Password unterstützt die Authentifizierung bei Azure-Datenquellen mit Microsoft Entra ID für native Benutzer oder Verbundbenutzer von Microsoft Entra. Bei Wahl dieses Modus müssen Benutzeranmeldeinformationen in der Verbindungszeichenfolge angegeben werden. Das folgende Beispiel zeigt, wie die Authentifizierung Active Directory Password verwendet wird.

// Use your own server, database, user ID, and password.
string ConnectionString = @"Server=demo.database.windows.net;"
   + "Authentication=Active Directory Password; Encrypt=True; Database=testdb;"
   + "User Id=user@domain.com; Password=<password>";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Nutzung der integrierten Authentifizierung

Um den Authentifizierungsmodus Active Directory Integrated zu verwenden, müssen Sie über eine lokale Active Directory Instanz verfügen, die mit Microsoft Entra ID in der Cloud verknüpft ist. Einen Verbund können Sie beispielsweise mithilfe von Active Directory-Verbunddienste (AD FS) einrichten.

Wenn Sie bei einem in die Domäne eingebundenen Computer angemeldet sind, können Sie in diesem Modus auf Azure SQL-Datenquellen zugreifen, ohne zur Eingabe von Anmeldeinformationen aufgefordert zu werden. In der Verbindungszeichenfolge für .NET Framework-Anwendungen können Sie nicht den Benutzernamen und das Kennwort angeben. Für .NET Core- und .NET Standard-Anwendungen ist der Benutzername in der Verbindungszeichenfolge optional. Die Credential-Eigenschaft von SqlConnection kann in diesem Modus nicht festgelegt werden.

Der folgende Codeausschnitt ist ein Beispiel der Verwendung der Active Directory Integrated-Authentifizierung.

// Use your own server and database.
string ConnectionString1 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Integrated; Encrypt=True; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString1)) {
    conn.Open();
}

// User ID is optional for .NET Core and .NET Standard.
string ConnectionString2 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Integrated; Encrypt=True; Database=testdb;"
  + "User Id=user@domain.com";

using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
    conn.Open();
}

Verwendung der interaktiven Authentifizierung

Der Authentifizierungsmodus Active Directory Interactive unterstützt zum Herstellen einer Verbindung mit Azure SQL-Datenquellen eine mehrstufige Authentifizierungstechnologie. Wenn Sie diesen Authentifizierungsmodus in der Verbindungszeichenfolge angeben, wird ein Bildschirm zur Authentifizierung bei Azure angezeigt, auf dem der Benutzer zur Eingabe gültiger Anmeldeinformationen aufgefordert wird. Sie können das Kennwort nicht in der Verbindungszeichenfolge eingeben.

Die Credential-Eigenschaft von SqlConnection kann in diesem Modus nicht festgelegt werden. Ab Microsoft.Daten.SqlClient 2.0.0 ist der Benutzername in der Verbindungszeichenfolge zulässig, sofern Sie sich im interaktiven Modus befinden.

Das folgende Beispiel zeigt, wie die Authentifizierung Active Directory Interactive verwendet wird.

// Use your own server, database, and user ID.
// User ID is optional.
string ConnectionString1 = @"Server=demo.database.windows.net;"
   + "Authentication=Active Directory Interactive; Encrypt=True;" 
   + "Database=testdb; User Id=user@domain.com";

using (SqlConnection conn = new SqlConnection(ConnectionString1)) {
    conn.Open();
}

// User ID is not provided.
string ConnectionString2 = @"Server=demo.database.windows.net;"
   + "Authentication=Active Directory Interactive; Encrypt=True;"
   + "Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
    conn.Open();
}

Verwenden der Dienstprinzipalauthentifizierung

Im Authentifizierungsmodus Active Directory Service Principal kann die Clientanwendung eine Verbindung mit Azure-SQL-Datenquellen herstellen, und zwar durch Angabe der Client-ID und des Geheimnisses einer Dienstprinzipalidentität. Die Dienstprinzipalauthentifizierung umfasst Folgendes:

  1. Einrichten einer App-Registrierung mit einem Geheimnis
  2. Erteilen von Berechtigungen für die App in der Azure SQL-Datenbankinstanz
  3. Herstellen der Verbindung mit den richtigen Anmeldeinformationen

Das folgende Beispiel zeigt, wie die Authentifizierung Active Directory Service Principal verwendet wird.

// Use your own server, database, app ID, and secret.
string ConnectionString = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Service Principal; Encrypt=True;"
  + "Database=testdb; User Id=AppId; Password=<password>";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Verwendung der Authentifizierung mit Gerätecodeflow

Mithilfe der Microsoft Authentication Library für .NET (MSAL.NET) ermöglicht die Active Directory Device Code Flow-Authentifizierung, dass die Clientanwendung mit Azure SQL-Datenquellen über Geräte und Betriebssysteme, die keinen interaktiven Webbrowser haben, verbunden wird. Die interaktive Authentifizierung erfolgt auf einem anderen Gerät. Weitere Informationen zur Gerätecodeflow-Authentifizierung finden Sie unter OAuth 2.0-Gerätecodeflow.

Bei Wahl dieses Modus können Sie nicht die Credential-Eigenschaft von SqlConnection festlegen. Außerdem dürfen Benutzername und Kennwort nicht in der Verbindungszeichenfolge angegeben werden.

Der folgende Codeausschnitt ist ein Beispiel der Verwendung der Active Directory Device Code Flow-Authentifizierung.

Hinweis

Das Timeout für Active Directory Device Code Flow wird standardmäßig auf die Einstellung Connect Timeout der Verbindung festgelegt. Stellen Sie sicher, dass Sie einen Wert für Connect Timeout angeben, der genügend Zeit zum Durchlaufen des Authentifizierungsprozesses für den Gerätecodeflow bietet.

// Use your own server and database and increase Connect Timeout as needed for
// device code flow.
string ConnectionString = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Device Code Flow; Encrypt=True;"
  + "Database=testdb; Connect Timeout=180;";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Verwendung der Authentifizierung mit verwalteter Identität

Die Authentifizierung mit verwalteten Identitäten für Azure-Ressourcen ist die empfohlene Authentifizierungsmethode für den programmgesteuerten Zugriff auf SQL. Eine Clientanwendung kann die vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität einer Ressource verwenden, um sich bei SQL mit Microsoft Entra D zu authentifizieren, indem die Identität bereitgestellt und zum Abrufen von Zugriffstokens verwendet wird. Durch diese Methode entfällt die Verwaltung von Anmeldedaten und Geheimnissen, was die Zugriffsverwaltung vereinfacht.

Es gibt zwei Arten von verwalteten Identitäten:

  • Die systemseitig zugewiesene verwaltete Identität wird als Teil einer Azure-Ressource (z. B. Ihrer SQL Managed Instance oder dem logischen Server) erstellt und teilt den Lebenszyklus dieser Ressource. Systemseitig zugewiesene Identitäten können nur einer einzigen Azure-Ressource zugeordnet werden.
  • Eine benutzerseitig zugewiesene verwaltete Identität wird als eigenständige Azure-Ressource erstellt und kann einer oder mehreren Instanzen eines Azure-Diensts zugewiesen werden.

Weitere Informationen zu verwalteten Identitäten finden Sie unter Was sind verwaltete Identitäten für Azure-Ressourcen?.

Ab Microsoft.Daten.SqlClient 2.1.0 unterstützt der Treiber die Authentifizierung bei Azure SQL-Datenbank, Azure Synapse Analytics und Azure SQL Managed Instance durch den Bezug von Zugriffstoken über eine verwaltete Identität. Für diese Authentifizierung müssen Sie in der Verbindungszeichenfolge entweder Active Directory Managed Identity oder Active Directory MSI angeben, wobei kein Kennwort erforderlich ist. Die Credential-Eigenschaft von SqlConnection kann in diesem Modus auch nicht festgelegt werden.

Bei einer benutzerseitig zugewiesenen verwalteten Identität muss die Client-ID der verwalteten Identität angegeben werden, wenn Microsoft.Data.SqlClient ab Version 3.0 verwendet wird. Wenn Microsoft.Data.SqlClient ab Version 2.1 verwendet wird, muss die Objekt-ID der verwalteten Identität angegeben werden.

Im folgenden Beispiel wird gezeigt, wie die Active Directory Managed Identity-Authentifizierung mit einer systemseitig zugewiesenen verwalteten Identität verwendet wird.

// For system-assigned managed identity
// Use your own values for Server and Database.
string ConnectionString1 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Managed Identity; Encrypt=True;"
  + "Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString1)) {
    conn.Open();
}

string ConnectionString2 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory MSI; Encrypt=True; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
    conn.Open();
}

Im folgenden Beispiel wird die Active Directory Managed Identity-Authentifizierung mit einer benutzerseitig zugewiesenen verwalteten Identität bei Microsoft.Data.SqlClient ab Version 3.0 veranschaulicht.

// For user-assigned managed identity
// Use your own values for Server, Database, and User Id.

// With Microsoft.Data.SqlClient v3.0+
string ConnectionString1 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Managed Identity; Encrypt=True;"
  + "User Id=ClientIdOfManagedIdentity; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString1)) {
    conn.Open();
}

// With Microsoft.Data.SqlClient v3.0+
string ConnectionString2 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory MSI; Encrypt=True;"
  + "User Id=ClientIdOfManagedIdentity; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
    conn.Open();
}

Im folgenden Beispiel wird die Active Directory Managed Identity-Authentifizierung mit einer benutzerseitig zugewiesenen verwalteten Identität bei Microsoft.Data.SqlClient 2.1 veranschaulicht.

// For user-assigned managed identity
// Use your own values for Server, Database, and User Id.

// With Microsoft.Data.SqlClient v2.1
string ConnectionString1 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Managed Identity; Encrypt=True;"
  + "User Id=ObjectIdOfManagedIdentity; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString1)) {
    conn.Open();
}

// With Microsoft.Data.SqlClient v2.1
string ConnectionString2 = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory MSI; Encrypt=True;"
  + "User Id=ObjectIdOfManagedIdentity; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
    conn.Open();
}

Verwendung der Standardauthentifizierung

Ab Version 3.0 erweitert dieser Authentifizierungsmodus die Möglichkeiten der Benutzerauthentifizierung. Dieser Modus erweitert die Anmeldelösungen auf die Clientumgebung, Visual Studio Code, Visual Studio, die Azure CLI usw.

Bei diesem Authentifizierungsmodus erhält der Treiber ein Token, indem er DefaultAzureCredential aus der Azure Identity-Bibliothek übergibt, um ein Zugriffstoken zu erhalten. In diesem Modus wird versucht, mit einem Satz von Anmeldatentypen ein Zugriffstoken abzurufen. Je nach verwendeter Version der Azure Identity-Bibliothek ist der Anmeldedatensatz unterschiedlich. Versionsspezifische Unterschiede sind in der Liste aufgeführt. Informationen zum spezifischen Verhalten je nach Azure Identity-Version finden Sie in den Dokumenten zur Azure.Identity-API.

  • EnvironmentCredential
    • Ermöglicht die Authentifizierung bei Microsoft Entra ID mit Client und Geheimnis oder mit Benutzername und Kennwort. Dabei müssen folgende Umgebungsvariablen konfiguriert werden: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Weitere Informationen)
  • WorkloadIdentityCredential
    • Ermöglicht die Microsoft Entra Workload ID-Authentifizierung auf Kubernetes und anderen Hosts, die die Workload Identity unterstützen. Weitere Informationen finden Sie unter Microsoft Entra Workload ID. Verfügbar ab Azure Identity-Version 1.10 und Microsoft.Data.SqlClient 5.1.4.
  • ManagedIdentityCredential
    • Authentifizierung bei Microsoft Entra ID mit einer verwalteten Identität, die der Bereitstellungsumgebung zugewiesen ist. „Client-ID“ und „Benutzerseitig zugewiesene verwaltete Identität“ werden aus der Verbindungseigenschaft „Benutzer-ID“ ausgelesen.
  • SharedTokenCacheCredential
    • Authentifizierung mit Token in dem von Microsoft-Anwendungen gemeinsam genutzten lokalen Cache.
  • VisualStudioCredential
    • Ermöglicht die Authentifizierung mit Microsoft Entra ID anhand von Daten aus Visual Studio
  • VisualStudioCodeCredential
    • Ermöglicht die Authentifizierung mit Microsoft Entra ID anhand von Daten aus Visual Studio Code.
  • AzurePowerShellCredential
    • Ermöglicht die Authentifizierung bei Microsoft Entra ID über Azure PowerShell. Verfügbar ab Azure Identity-Version 1.6 und Microsoft.Data.SqlClient 5.0.
  • AzureCliCredential
    • Ermöglicht die Authentifizierung mit Microsoft Entra ID mithilfe der Azure CLI, um ein Zugriffstoken abzurufen.
  • AzureDeveloperCliCredential
    • Ermöglicht die Authentifizierung mit Microsoft Entra ID über die Azure Developer CLI zum Abrufen eines Zugriffstokens. Verfügbar ab Azure Identity-Version 1.10 und Microsoft.Data.SqlClient 5.1.4.

Hinweis

InteractiveBrowserCredential ist in der Treiberimplementierung von „Active Directory Default“ deaktiviert. „Active Directory Interactive“ ist die einzige verfügbare Option zum Abrufen eines Tokens mithilfe der MFA/interaktiven Authentifizierung.

Weitere Anpassungsoptionen sind derzeit nicht verfügbar.

Im folgenden Beispiel wird die Verwendung der Active Directory Default-Authentifizierung veranschaulicht.

// Use your own server, database
string ConnectionString = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Default; Encrypt=True; Database=testdb;";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Verwenden der Workload Identity Authentication

Ab Version 5.2 verfügbar, z. B. bei verwalteten Identitäten, verwendet der Workload-Identitäts-Authentifizierungsmodus den Wert des Parameters User ID im Verbindungszeichenfolge für die Client-ID, sofern angegeben. Im Gegensatz zu verwalteter Identität verwendet WorkloadIdentityCredentialOptions den Wert jedoch aus Umgebungsvariablen: AZURE_TENANT_ID, AZURE_CLIENT_ID und AZURE_FEDERATED_TOKEN_FILE. Allerdings kann nur die Client-ID von der Verbindungszeichenfolge außer Kraft gesetzt werden.

Im folgenden Beispiel wird die Active Directory Workload Identity-Authentifizierung mit einer benutzerseitig zugewiesenen verwalteten Identität bei Microsoft.Data.SqlClient v5.2 und höher veranschaulicht.

// Use your own values for Server, Database, and User Id.
// With Microsoft.Data.SqlClient v5.2+
string ConnectionString = @"Server=demo.database.windows.net;"
  + "Authentication=Active Directory Workload Identity; Encrypt=True;"
  + "User Id=ClientIdOfManagedIdentity; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Anpassen der Microsoft Entra-Authentifizierung

Neben der Verwendung der in den Treiber integrierten Microsoft Entra-Authentifizierung wird ab Microsoft.Data.SqlClient 2.1.0 Anwendungen die Möglichkeit geboten, die Microsoft Entra-Authentifizierung anzupassen. Die Anpassung basiert auf der ActiveDirectoryAuthenticationProvider-Klasse, die der abstrakten SqlAuthenticationProvider-Klasse abgeleitet ist.

Während der Microsoft Entra-Authentifizierung kann die Clientanwendung ihre eigene ActiveDirectoryAuthenticationProvider-Klasse wie folgt definieren:

  • Durch Verwenden einer angepassten Rückrufmethode
  • Durch Übergeben einer Anwendungsclient-ID an die MSAL-Bibliothek über den SqlClient-Treiber zum Abrufen von Zugriffstoken

Das folgende Beispiel zeigt, wie bei Verwendung der Active Directory Device Code Flow-Authentifizierung ein benutzerdefinierter Rückruf erfolgt.

using System;
using System.Threading.Tasks;
using Microsoft.Identity.Client;
using Microsoft.Data.SqlClient;

namespace CustomAuthenticationProviderExamples
{
    public class Program
    {
        public static void Main()
        {
            SqlAuthenticationProvider authProvider = new ActiveDirectoryAuthenticationProvider(CustomDeviceFlowCallback);
            SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow, authProvider);
            using (SqlConnection sqlConnection = new SqlConnection("Server=<myserver>.database.windows.net;Authentication=Active Directory Device Code Flow;Database=<db>;"))
            {
                sqlConnection.Open();
                Console.WriteLine("Connected successfully!");
            }
        }

        private static Task CustomDeviceFlowCallback(DeviceCodeResult result)
        {
            // Provide custom logic to process result information and read device code.
            Console.WriteLine(result.Message);
            return Task.FromResult(0);
        }
    }
}

Mit einer angepassten ActiveDirectoryAuthenticationProvider-Klasse kann eine benutzerdefinierte Clientanwendungs-ID an SqlClient übergeben werden, sofern ein unterstützter Microsoft Entra-Authentifizierungsmodus eingesetzt wird. Zu den unterstützten Microsoft Entra-Authentifizierungsmodi gehören Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principal und Active Directory Device Code Flow.

Die Anwendungsclient-ID lässt sich auch über SqlAuthenticationProviderConfigurationSection oder SqlClientAuthenticationProviderConfigurationSection konfigurieren. Die Konfigurationseigenschaft applicationClientId gilt für .NET Framework ab  4.6 und .Net Core ab 2.1.

Der folgende Codeausschnitt ist ein Beispiel für die Verwendung einer benutzerdefinierten ActiveDirectoryAuthenticationProvider-Klasse mit einer benutzerdefinierten Clientanwendungs-ID, wenn die Active Directory Interactive-Authentifizierung verwendet wird.

using System;
using Microsoft.Data.SqlClient;

namespace CustomAuthenticationProviderExamples
{
    public class Program
    {
        public static void Main()
        {
            // Supported for all authentication modes supported by ActiveDirectoryAuthenticationProvider
            ActiveDirectoryAuthenticationProvider provider = new ActiveDirectoryAuthenticationProvider("<application_client_id>");
            if (provider.IsSupported(SqlAuthenticationMethod.ActiveDirectoryInteractive))
            {
                SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, provider);
            }
            
            using (SqlConnection sqlConnection = new SqlConnection("Server=<myserver>.database.windows.net;Authentication=Active Directory Interactive;Database=<db>;"))
            {
                sqlConnection.Open();
                Console.WriteLine("Connected successfully!");
            }
        }
    }
}

Das folgende Beispiel zeigt, wie die Client-ID einer Anwendung in einem Konfigurationsabschnitt festgelegt wird.

<configuration>
  <configSections>
    <section name="SqlClientAuthenticationProviders"
             type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
  </configSections>
  <SqlClientAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

<!--or-->

<configuration>
  <configSections>
    <section name="SqlAuthenticationProviders"
             type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
  </configSections>
  <SqlAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

Verwenden von AccessTokenCallback

Ab Version 5.2 ist eine neue AccessTokenCallback-Eigenschaft für SqlConnection verfügbar. Verwenden Sie die AccessTokenCallback-Eigenschaft, um eine angepasste Funktion zu definieren, die ein Zugriffstoken aufgrund der eingehenden Parameter zurückgibt. Die Verwendung des Rückrufs ist besser als die Verwendung der AccessToken-Eigenschaft, da das Zugriffstoken innerhalb eines Verbindungspools aktualisiert werden kann. Bei Verwendung der AccessToken-Eigenschaft kann das Token nach dem Öffnen der Verbindung nicht aktualisiert werden. Es gibt auch kein zugeordnetes Ablaufdatum, das über die Eigenschaft bereitgestellt wird. Sobald das Token abläuft, schlagen neue Verbindungsanforderungen mit einem Serverauthentifizierungsfehler fehl, und Pools, die es verwenden, müssen manuell gelöscht werden.

Der folgende Codeschnipsel ist ein Beispiel für die Verwendung der AccessTokenCallback-Eigenschaft in Microsoft.Data.SqlClient v5.2 und neuer.

using System.Collections.Concurrent;
using System.Threading;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Identity;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        OpenSqlConnection();
        Console.ReadLine();
    }

    const string defaultScopeSuffix = "/.default";

    // Reuse credential objects to take advantage of underlying token caches
    private static ConcurrentDictionary<string, DefaultAzureCredential> credentials = new ConcurrentDictionary<string, DefaultAzureCredential>();

    // Use a shared callback function for connections that should be in the same connection pool
    private static Func<SqlAuthenticationParameters, CancellationToken, Task<SqlAuthenticationToken>> myAccessTokenCallback =
        async (authParams, cancellationToken) =>
        {
            string scope = authParams.Resource.EndsWith(defaultScopeSuffix)
                ? authParams.Resource
                : $"{authParams.Resource}{defaultScopeSuffix}";

            DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions();
            options.ManagedIdentityClientId = authParams.UserId;

            // Reuse the same credential object if we are using the same MI Client Id
            AccessToken token = await credentials.GetOrAdd(authParams.UserId, new DefaultAzureCredential(options)).GetTokenAsync(
                new TokenRequestContext(new string[] { scope }),
                cancellationToken);

            return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
        };

    private static void OpenSqlConnection()
    {
        // (Optional) Pass a User-Assigned Managed Identity Client ID.
        // This will ensure different MI Client IDs are in different connection pools.
        string connectionString = "Server=myServer.database.windows.net;Encrypt=Mandatory;UserId=<ManagedIdentitityClientId>;";

        using (SqlConnection connection = new SqlConnection(connectionString)
        {
            // The callback function is part of the connection pool key. Using a static callback function
            // ensures connections will not create a new pool per connection just for the callback.
            AccessTokenCallback = myAccessTokenCallback
        })
        {
            connection.Open();
            Console.WriteLine("ServerVersion: {0}", connection.ServerVersion);
            Console.WriteLine("State: {0}", connection.State);
        }
    }
}

Unterstützung eines benutzerdefinierten SQL-Authentifizierungsanbieters

Angesichts der größeren Flexibilität kann die Clientanwendung auch ihren eigenen Anbieter für die Microsoft Entra-Authentifizierung anstelle der ActiveDirectoryAuthenticationProvider-Klasse verwenden. Der benutzerdefinierte Authentifizierungsanbieter muss eine Unterklasse von SqlAuthenticationProvider mit überschriebenen Methoden sein. Anschließend muss der benutzerdefinierte Anbieter registriert und dadurch mindestens eine der vorhandenen Active Directory*-Authentifizierungsmethoden überschrieben werden.

Das folgende Beispiel zeigt, wie zur Active Directory Device Code Flow-Authentifizierung ein neuer Authentifizierungsanbieter verwendet wird.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;
using Microsoft.Identity.Client;

namespace CustomAuthenticationProviderExamples
{
    /// <summary>
    /// Example demonstrating creating a custom device code flow authentication provider and attaching it to the driver.
    /// This is helpful for applications that wish to override the Callback for the Device Code Result implemented by the SqlClient driver.
    /// </summary>
    public class CustomDeviceCodeFlowAzureAuthenticationProvider : SqlAuthenticationProvider
    {
        private const string ClientId = "my-client-id";
        private const string ClientName = "My Application Name";
        private const string DefaultScopeSuffix = "/.default";

        // Maintain a copy of the PublicClientApplication object to cache the underlying access tokens it provides
        private static IPublicClientApplication pcApplication;

        public override async Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters)
        {
            string[] scopes = [ parameters.Resource.EndsWith(DefaultScopeSuffix) ? parameters.Resource : parameters.Resource + DefaultScopeSuffix ];

            IPublicClientApplication app = pcApplication;
            if (app == null)
            {
                pcApplication = app = PublicClientApplicationBuilder.Create(ClientId)
                    .WithAuthority(parameters.Authority)
                    .WithClientName(ClientName)
                    .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                    .Build();
            }

            AuthenticationResult result;
            using CancellationTokenSource connectionTimeoutCancellation = new CancellationTokenSource(TimeSpan.FromSeconds(parameters.ConnectionTimeout));

            try
            {
                IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
                result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
                    .ExecuteAsync(connectionTimeoutCancellation.Token);
            }
            catch (MsalUiRequiredException)
            {
                result = await app.AcquireTokenWithDeviceCode(scopes, deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult))
                    .ExecuteAsync(connectionTimeoutCancellation.Token);
            }

            return new SqlAuthenticationToken(result.AccessToken, result.ExpiresOn);
        }

        public override bool IsSupported(SqlAuthenticationMethod authenticationMethod)
            => authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);

        private static Task CustomDeviceFlowCallback(DeviceCodeResult result)
        {
            Console.WriteLine(result.Message);
            return Task.CompletedTask;
        }
    }

    public class Program
    {
        public static void Main()
        {
            // Register our custom authentication provider class to override Active Directory Device Code Flow
            SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow, new CustomDeviceCodeFlowAzureAuthenticationProvider());
            using (SqlConnection sqlConnection = new SqlConnection("Server=<myserver>.database.windows.net;Authentication=Active Directory Device Code Flow;Database=<db>;"))
            {
                sqlConnection.Open();
                Console.WriteLine("Connected successfully!");
            }
        }
    }
}

Zusätzlich zur verbesserten Active Directory Interactive-Authentifizierung werden ab Microsoft.Data.SqlClient 2.1.0 die folgenden APIs für Clientanwendungen bereitgestellt, um die interaktive und Gerätecodeflow-Authentifizierung anzupassen.

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    // Sets a reference to the current System.Windows.Forms.IWin32Window that triggers
    // the browser to be shown. 
    // Used to center the browser pop-up onto this window.
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    // Sets a reference to the ViewController (if using Xamarin.iOS), Activity
    // (if using Xamarin.Android) IWin32Window, or IntPtr (if using .NET Framework). 
    // Used for invoking the browser for Active Directory Interactive authentication.
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core, and .NET Standard targeted applications
    // Sets a callback method that's invoked with a custom web UI instance that lets
    // the user sign in with Azure AD, present consent if needed, and get back the
    // authorization code. 
    // Applicable when working with Active Directory Interactive authentication.
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken,
                                       Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core, and .NET Standard targeted applications
    // Clears cached user tokens from the token provider.
    public static void ClearUserTokenCache();
}

Siehe auch