Sdílet prostřednictvím

Připojení k Azure SQL pomocí ověřování Microsoft Entra a SqlClient

Platí pro: .NET Framework .NET Standard

Stáhnout ADO.NET

Tento článek popisuje, jak se připojit ke zdrojům dat Azure SQL pomocí ověřování Microsoft Entra z aplikace .NET pomocí SqlClient.

Poznámka:

I když je Microsoft Entra ID novým názvem pro Azure Active Directory (Azure AD), aby nedošlo k narušení stávajících prostředí, Azure AD stále zůstává v některých pevně zakódovaných prvcích, jako jsou pole uživatelského rozhraní, zprostředkovatelé připojení, chybové kódy a příkazy cmdlet. V tomto článku jsou tyto dva názvy zaměnitelné.

Přehled

Ověřování Microsoft Entra používá identity v MICROSOFT Entra ID pro přístup ke zdrojům dat, jako jsou Azure SQL Database, Azure SQL Managed Instance a Azure Synapse Analytics. Obor názvů Microsoft.Data.SqlClient umožňuje klientským aplikacím určit přihlašovací údaje Microsoft Entra v různých režimech ověřování při připojování ke službě Azure SQL Database a azure SQL Managed Instance. Pokud chcete používat ověřování Microsoft Entra s Azure SQL, musíte nakonfigurovat a spravovat ověřování Microsoft Entra pomocí Azure SQL.

Když nastavíte vlastnost připojení Authentication v připojovacím řetězci, klient může zvolit upřednostňovaný režim ověřování Microsoft Entra podle zadané hodnoty:

  • Nejstarší verze Microsoft.Data.SqlClient podporuje Active Directory Password pro rozhraní .NET Framework, .NET Core a .NET Standard. Podporuje také ověřování Active Directory Integrated a ověřování Active Directory Interactive pro rozhraní .NET Framework.

  • Počínaje Microsoft.Data.SqlClient 2.0.0 se podpora ověřování Active Directory Integrated a ověřování Active Directory Interactive rozšiřuje v rozhraní .NET Framework, .NET Core a .NET Standard.

    Do sqlClient 2.0.0 se přidá také nový režim ověřování Active Directory Service Principal. K ověření identity se používá ID klienta a tajný klíč identity služebního principála pro účely autentizace.

  • V Microsoft.Data.SqlClient 2.1.0 se přidávají další režimy ověřování, včetně Active Directory Device Code Flow a Active Directory Managed Identity (označovaných také jako Active Directory MSI). Tyto nové režimy umožňují aplikaci získat přístupový token pro připojení k serveru.

Informace o ověřování Microsoft Entra nad rámec toho, co následující části popisují, naleznete v tématu Použití ověřování Microsoft Entra.

Nastavení ověřování Microsoft Entra

Když se aplikace připojuje ke zdrojům dat Azure SQL pomocí ověřování Microsoft Entra, musí poskytnout platný režim ověřování. Následující tabulka uvádí podporované režimy ověřování. Aplikace určuje režim pomocí vlastnosti připojení Authentication v připojovacím řetězci.

Hodnota Popis Verze Microsoft.Data.SqlClient
Heslo služby Active Directory Ověřování pomocí uživatelského jména a hesla identity Microsoft Entra 1.0+
Integrovaná služba Active Directory Ověřování pomocí identity Microsoft Entra pomocí integrovaného ověřování systému Windows (IWA) 2.0.0+1
Interaktivní služba Active Directory Ověřování pomocí identity Microsoft Entra pomocí interaktivního ověřování 2.0.0+1
Instanční objekt služby Active Directory Ověřte se pomocí principála služby Microsoft Entra s použitím ID klienta a tajemství 2.0.0+
Tok kódu zařízení služby Active Directory Ověřování pomocí identity Microsoft Entra pomocí režimu toku kódu zařízení 2.1.0+
Spravovaná identita služby Active Directory
Active Directory MSI		 Ověření pomocí systémem přiřazené nebo uživatelem přiřazené spravované identity Microsoft Entra 2.1.0+
Výchozí nastavení služby Active Directory Ověřování pomocí identity Microsoft Entra bez hesla a neinteraktivních mechanismů, včetně spravovaných identit, editoru Visual Studio Code, sady Visual Studio, Azure CLI atd. 3.0.0+
Identita úloh služby Active Directory Ověřte se pomocí identity Microsoft Entra použitím uživatelsky přiřazené spravované identity pro připojení ke službě SQL Database z prostředí klientů Azure, která jsou povolena pro pracovní identity. 5.2.0+

1 Před Microsoft.Data.SqlClient 2.0.0 se režimy ověřování Active Directory Integrateda Active Directory Interactive podporují pouze v rozhraní .NET Framework.

Použití ověřování heslem

Active Directory Password režim ověřování podporuje ověřování ve zdrojích dat Azure s ID Microsoft Entra pro nativní nebo federované uživatele Microsoft Entra. Pokud používáte tento režim, musí být v připojovacím řetězci zadané přihlašovací údaje uživatele. Následující příklad ukazuje, jak používat ověřování Active Directory Password.

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

Použití integrovaného ověřování

Pokud chcete použít režim ověřování Active Directory Integrated, musíte mít místní instanci služby Active Directory, která je připojená k ID Microsoft Entra v cloudu. Můžete federovat pomocí služby Active Directory Federation Services (AD FS), například.

Když jste přihlášení k počítači připojenému k doméně, můžete přistupovat ke zdrojům dat Azure SQL bez výzvy k zadání přihlašovacích údajů v tomto režimu. V připojovacím řetězci pro aplikace .NET Framework nelze zadat uživatelské jméno a heslo. Uživatelské jméno je volitelné v připojovacím řetězci pro aplikace .NET Core a .NET Standard. V tomto režimu nelze nastavit vlastnost Credential SqlConnection.

Následující fragment kódu je příkladem, kdy se používá ověřování Active Directory Integrated.

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

Použití interaktivního ověřování

Active Directory Interactive ověřování podporuje vícefaktorové technologie ověřování pro připojení ke zdrojům dat Azure SQL. Pokud tento režim ověřování zadáte v připojovacím řetězci, zobrazí se obrazovka ověřování Azure a vyzve uživatele, aby zadal platné přihlašovací údaje. V připojovacím řetězci nemůžete zadat heslo.

V tomto režimu nelze nastavit vlastnost Credential SqlConnection. S Microsoft.Data.SqlClient 2.0.0 a novějšími je v interaktivním modu povoleno uživatelské jméno v připojovacím řetězci.

Následující příklad ukazuje, jak používat ověřování Active Directory Interactive.

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

Použití ověřování služebního principálu

V Active Directory Service Principal režimu ověřování se klientská aplikace může připojit ke zdrojům dat Azure SQL tak, že poskytne ID klienta a tajný klíč identity instančního objektu. Ověřování hlavní služby zahrnuje:

  1. Nastavení registrace aplikace s tajným kódem
  2. Udělení oprávnění aplikaci v instanci služby Azure SQL Database
  3. Připojení pomocí správných přihlašovacích údajů

Následující příklad ukazuje, jak používat ověřování Active Directory Service Principal.

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

Ověřování toku kódu zařízení

S Microsoft Authentication Library pro .NET (MSAL.NET) Active Directory Device Code Flow ověřování umožňuje klientské aplikaci připojit se ke zdrojům dat Azure SQL ze zařízení a operačních systémů, které nemají interaktivní webový prohlížeč. Interaktivní ověřování se provádí na jiném zařízení. Další informace o ověřování toku kódu zařízení najdete v tématu OAuth 2.0 Tok kódu zařízení.

Pokud je tento režim používán, nemůžete nastavit vlastnost Credential objektu SqlConnection. Také uživatelské jméno a heslo nesmí být zadané v připojovacím řetězci.

Následující fragment kódu je příkladem použití ověřování Active Directory Device Code Flow.

Poznámka:

Časový limit pro Active Directory Device Code Flow je ve výchozím nastavení podle nastavení připojení Connect Timeout. Nezapomeňte zadat Connect Timeout, která poskytuje dostatek času na procházení procesu ověřování toku kódu zařízení.

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

Použití ověřování spravované identity

Ověřování pomocí spravovaných identit pro prostředky Azure je doporučená metoda ověřování pro programový přístup k SQL. Klientská aplikace může použít spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem prostředku k ověření v SQL pomocí Microsoft Entra ID tím, že identitu poskytne a použije k získání přístupových tokenů. Tato metoda eliminuje potřebu spravovat přihlašovací údaje a tajné kódy a může zjednodušit správu přístupu.

Existují dva typy spravovaných identit:

  • Spravovaná identita přiřazená systémem je vytvořena jako součást prostředku Azure (například vaše spravovaná instance SQL nebo logický server) a sdílí životní cyklus tohoto prostředku. Identity přiřazené systémem je možné přidružit pouze k jednomu prostředku Azure.
  • Spravovaná identita přiřazená uživatelem je vytvořena jako nezávislý prostředek Azure. Dá se přiřadit k jedné nebo více instancím služby Azure.

Další informace o spravovaných identitách najdete v tématu O spravovaných identitách pro prostředky Azure.

Od verze Microsoft.Data.SqlClient 2.1.0 ovladač podporuje ověřování pro Azure SQL Database, Azure Synapse Analytics a Azure SQL Managed Instance pomocí spravované identity. Pokud chcete toto ověřování použít, zadejte v připojovacím řetězci Active Directory Managed Identity nebo Active Directory MSI a nevyžaduje se žádné heslo. V tomto režimu nemůžete nastavit ani vlastnost Credential u SqlConnection.

Pro uživatelsky přiřazenou spravovanou identitu musí být ID klienta spravované identity uvedeno při použití Microsoft.Data.SqlClient verze 3.0 nebo novější. Pokud používáte Microsoft.Data.SqlClient v2.1, musí být zadáno ID objektu spravované identity.

Následující příklad ukazuje, jak používat ověřování Active Directory Managed Identity se spravovanou identitou přiřazenou systémem.

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

Následující příklad ukazuje Active Directory Managed Identity ověřování pomocí spravované identity přiřazené uživatelem s Microsoft.Data.SqlClient od verze 3.0 výše.

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

Následující příklad ukazuje Active Directory Managed Identity ověřování pomocí spravované identity přiřazené uživatelem s Microsoft.Data.SqlClient v2.1.

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

Použití výchozího ověřování

K dispozici od verze 3.0 tento režim ověřování rozšiřuje možnosti ověřování uživatelů. Tento režim rozšiřuje řešení přihlášení do klientského prostředí, editoru Visual Studio Code, sady Visual Studio, Azure CLI atd.

V tomto režimu ověřování získá ovladač token předánímDefaultAzureCredentialz knihovny Azure Identity pro získání přístupového tokenu. Tento režim se pokusí použít sadu typů přihlašovacích údajů k získání přístupového tokenu v daném pořadí. V závislosti na používané verzi knihovny identit Azure se sada přihlašovacích údajů liší. Rozdíly specifické pro verzi jsou uvedeny v seznamu. Konkrétní chování verze azure Identity najdete v dokumentaci k rozhraní azure.Identity API.

Důležité

Výchozí služba Active Directory je praktickou možností, jak zjednodušit rozdíly připojovacího řetězce mezi různými prostředími. Může ale mít vliv na výkon, protože kvůli informacím o autentizaci musí hledat na více místech. Pokud se při použití výchozího nastavení služby Active Directory zobrazí pomalé připojení, použijte jinou možnost ověřování, která konkrétně cílí na metodu ověřování, kterou používáte ve svém prostředí. Výchozí nastavení služby Active Directory se nedoporučuje pro prostředí, která mají striktní dobu odezvy na úrovni služby.

  • Environmentální přihlašovací údaj
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí klientského ID a tajného klíče nebo uživatelského jména a hesla, údaje nakonfigurované v následujících proměnných prostředí: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Další podrobnosti)
  • WorkloadIdentityCredential
    • Umožňuje ověřování ID úloh Microsoft Entra v Kubernetes a dalších hostitelích podporujících identitu úloh. Další informace najdete v tématu ID úloh Microsoft Entra. K dispozici od verze 1.10 platformy Azure Identity a Microsoft.Data.SqlClient 5.1.4.
  • OprávněníSpravovanéIdentity
    • Pokusí se ověřit identitu pomocí Microsoft Entra ID se spravovanou identitou, která je přiřazena k nasazovacímu prostředí. ID klienta spravované identity přiřazené uživatelem se načte z vlastnosti připojení "ID uživatele".
  • SharedTokenCacheCredential
    • Ověřuje se pomocí tokenů v místní mezipaměti sdílené mezi aplikacemi Microsoftu.
  • VisualStudioCredential
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí dat ze sady Visual Studio.
  • VisualStudioCodeCredential
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí dat z editoru Visual Studio Code.
  • azurePowerShellCredential
    • Povolí ověřování pomocí Microsoft Entra ID pomocí Azure PowerShellu. K dispozici od Azure Identity verze 1.6 a Microsoft.Data.SqlClient 5.0.
  • AzureCliCredential
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí Azure CLI k získání přístupového tokenu.
  • azureDeveloperCliCredential
    • Umožňuje ověřování pro Microsoft Entra ID pomocí Azure Developer CLI k získání přístupového tokenu. K dispozici od verze 1.10 platformy Azure Identity a Microsoft.Data.SqlClient 5.1.4.

Poznámka:

InteractiveBrowserCredential je v implementaci výchozího nastavení služby Active Directory zakázaná a služba Active Directory Interactive je jedinou možností, jak získat token pomocí vícefaktorového ověřování nebo interaktivního ověřování.

V tuto chvíli nejsou k dispozici další možnosti přizpůsobení.

Následující příklad ukazuje, jak používat výchozí ověřování služby Active Directory.

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

Použití ověřování identit úloh

K dispozici od verze 5.2, jako u spravovaných identit, identita úlohy režim ověřování používá hodnotu parametru User ID v připojovacím řetězci pro id klienta, pokud je zadán. Na rozdíl od spravované identity ale WorkloadIdentityCredentialOptions nastaví výchozí hodnotu z proměnných prostředí: AZURE_TENANT_ID, AZURE_CLIENT_ID a AZURE_FEDERATED_TOKEN_FILE. Připojovací řetězec ale může přepsat pouze ID klienta.

Následující příklad ukazuje Active Directory Workload Identity ověřování pomocí uživatelsky přiřazené spravované identity s Microsoft.Data.SqlClient od verze 5.2.

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

Přizpůsobení ověřování Microsoft Entra

Kromě použití ověřování Microsoft Entra integrovaného do ovladače Microsoft.Data.SqlClient 2.1.0 a novějším poskytují aplikace možnost přizpůsobit ověřování Microsoft Entra. Přizpůsobení vychází z třídy ActiveDirectoryAuthenticationProvider, která je odvozena z SqlAuthenticationProvider abstraktní třídy.

Během ověřování Microsoft Entra může klientská aplikace definovat vlastní třídu ActiveDirectoryAuthenticationProvider buď:

  • Použití přizpůsobené metody zpětného volání.
  • Předání ID klienta aplikace do knihovny MSAL prostřednictvím ovladače SqlClient pro načtení přístupových tokenů

Následující příklad ukazuje, jak použít vlastní zpětné volání při použití Active Directory Device Code Flow ověřování.

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

namespace CustomDeviceCodeFlowAuthProviderExample
{
    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);
        }
    }
}

S přizpůsobenou ActiveDirectoryAuthenticationProvider třídou lze ID klienta aplikace definované uživatelem předat SqlClient, pokud se používá podporovaný režim ověřování Microsoft Entra. Podporované režimy ověřování Microsoft Entra zahrnují Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principala Active Directory Device Code Flow.

ID klienta aplikace je také možné konfigurovat prostřednictvím SqlAuthenticationProviderConfigurationSection nebo SqlClientAuthenticationProviderConfigurationSection. Vlastnost konfigurace applicationClientId platí pro rozhraní .NET Framework 4.6 nebo novější a .NET Core 2.1 nebo novější.

Následující fragment kódu je příkladem použití přizpůsobené třídy ActiveDirectoryAuthenticationProvider s ID klienta aplikace definované uživatelem při použití ověřování Active Directory Interactive.

using System;
using Microsoft.Data.SqlClient;

namespace CustomAppIdAuthProviderExample
{
    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!");
            }
        }
    }
}

Následující příklad ukazuje, jak nastavit ID klienta aplikace prostřednictvím oddílu konfigurace.

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

Použití AccessTokenCallbacku

Od verze 5.2 je na SqlConnectiondostupná nová vlastnost AccessTokenCallback. Pomocí vlastnosti AccessTokenCallback definujte vlastní funkci, která vrací přístupový token vzhledem k příchozím parametrům. Použití zpětného volání je lepší než použití vlastnosti AccessToken, protože umožňuje aktualizovat přístupový token v rámci fondu připojení. Při použití vlastnosti AccessToken se token po otevření připojení nedá aktualizovat. Pro vlastnost není k dispozici žádné přidružené datum vypršení platnosti. Jakmile platnost tokenu vyprší, nové žádosti o připojení selžou s chybou ověřování serveru a fondy, které ho používají, musí být vymazány ručně.

Důležité

Je nutné, aby AccessTokenCallback vrátil přístupové tokeny stejného kontextu zabezpečení pro stejné vstupní parametry. Pokud se kontext zabezpečení liší, může být pro požadavek na připojení vráceno sdružené připojení s nesprávným kontextem zabezpečení.

Poznámka:

AccessTokenCallback je součástí klíče používaného k identifikaci připojovacích fondů. Vyhněte se vytváření nového zpětného volání funkce pro každé vytvoření SqlConnection, protože výsledkem je pokaždé nový fond. Pro připojení, která mají být považována za vhodná pro sdružování, používejte stejnou instanci funkce. Klíč fondu připojení obsahuje parametry předané zpětnému volání, aby se správně rozdělily fondy připojení.

Následující fragment kódu je příkladem použití vlastnosti AccessTokenCallback v Microsoft.Data.SqlClient v5.2 dále.

using System;
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);
        }
    }
}

Podpora vlastního zprostředkovatele ověřování SQL

Vzhledem k větší flexibilitě může klientská aplikace místo použití třídy ActiveDirectoryAuthenticationProvider používat vlastního poskytovatele pro ověřování Microsoft Entra. Vlastní zprostředkovatel ověřování musí být podtřídou SqlAuthenticationProvider s přepsanými metodami. Poté musí zaregistrovat vlastního zprostředkovatele, čímž přepíše jednu nebo více stávajících metod ověřování Active Directory*.

Důležité

Zprostředkovatel ověřování musí vracet přístupové tokeny stejného kontextu zabezpečení pro stejné vstupní parametry. Pokud se kontext zabezpečení liší, může být pro požadavek na připojení vráceno sdružené připojení s nesprávným kontextem zabezpečení.

Následující příklad ukazuje, jak použít nového zprostředkovatele ověřování pro Active Directory Device Code Flow ověřování.

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 CustomDeviceCodeFlowAuthProviderExample
{
    /// <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!");
            }
        }
    }
}

Kromě vylepšení prostředí ověřování Active Directory Interactive poskytují Microsoft.Data.SqlClient 2.1.0 a novější pro klientské aplikace následující rozhraní API pro přizpůsobení interaktivního ověřování a ověřování pomocí kódu zařízení.

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 .NET for iOS), Activity
    // (if using .NET for 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();
}

Viz také

  • Last updated on