Dela via

Ansluta till Azure SQL med Microsoft Entra-autentisering och SqlClient

Gäller för: .NET Framework .NET .NET Standard

Ladda ned ADO.NET

Den här artikeln beskriver hur du ansluter till Azure SQL-datakällor med hjälp av Microsoft Entra-autentisering från ett .NET-program med SqlClient.

Anmärkning

Även om Microsoft Entra ID är det nya namnet för Azure Active Directory (Azure AD), för att undvika störningar i befintliga miljöer, kvarstår Azure AD fortfarande i vissa hårdkodade element som gränssnittsfält, anslutningsleverantörer, felkoder och cmdletar. I den här artikeln är de två namnen utbytbara.

Översikt

Microsoft Entra-autentisering använder identiteter i Microsoft Entra-ID för att komma åt datakällor som Azure SQL Database, Azure SQL Managed Instance och Azure Synapse Analytics. Med Microsoft.Data.SqlClient- namnområde kan klientprogram ange Microsoft Entra-autentiseringsuppgifter i olika autentiseringslägen när de ansluter till Azure SQL Database och Azure SQL Managed Instance. Om du vill använda Microsoft Entra-autentisering med Azure SQL måste du konfigurera och hantera Microsoft Entra-autentisering med Azure SQL.

När du anger Authentication anslutningsegenskap i anslutningssträngen kan klienten välja ett önskat Microsoft Entra-autentiseringsläge enligt det angivna värdet:

  • Den tidigaste Microsoft.Data.SqlClient-versionen stöder Active Directory Password för .NET Framework, .NET Core och .NET Standard. Den stöder också Active Directory Integrated autentisering och Active Directory Interactive-autentisering för .NET Framework.

  • Från och med Microsoft.Data.SqlClient 2.0.0 utökas stöd för Active Directory Integrated autentisering och Active Directory Interactive-autentisering i .NET Framework, .NET Core och .NET Standard.

    Ett nytt Active Directory Service Principal autentiseringsläge läggs också till i SqlClient 2.0.0. Den använder klient-ID:t och hemligheten för en tjänsthuvudnamnsidentitet för att utföra autentisering.

  • Fler autentiseringslägen läggs till i Microsoft.Data.SqlClient 2.1.0, inklusive Active Directory Device Code Flow och Active Directory Managed Identity (kallas även Active Directory MSI). Med de här nya lägena kan programmet hämta en åtkomsttoken för att ansluta till servern.

Information om Microsoft Entra-autentisering utöver vad som beskrivs i följande avsnitt finns i Använda Microsoft Entra-autentisering.

Ange Microsoft Entra-autentisering

När programmet ansluter till Azure SQL-datakällor med hjälp av Microsoft Entra-autentisering måste det tillhandahålla ett giltigt autentiseringsläge. I följande tabell visas de autentiseringslägen som stöds. Applikationen anger ett läge med hjälp av anslutningsegenskapen Authentication i anslutningssträngen.

Värde Beskrivning Microsoft.Data.SqlClient-version
Active Directory-lösenord Autentisera med en Microsoft Entra-identitets användarnamn och lösenord 1.0+
Active Directory Integrerat Autentisera med en Microsoft Entra-identitet med hjälp av integrerad Windows-autentisering (IWA) 2.0.0+1
Active Directory Interaktiv Autentisera med en Microsoft Entra-identitet med hjälp av interaktiv autentisering 2.0.0+1
Active Directory-tjänstens huvudnamn Autentisera med ett servicehuvud för Microsoft Entra genom dess klient-ID och hemliga nyckel. 2.0.0+
Active Directory-enhetskodflöde Autentisera med en Microsoft Entra-identitet med hjälp av flödesläge för enhetskod 2.1.0+
Hanterad identitet för Active Directory
Active Directory MSI		 Autentisera med en Microsoft Entra-systemtilldelad eller användartilldelad hanterad identitet 2.1.0+
Active Directory-standard Autentisera med en Microsoft Entra-identitet med hjälp av lösenordslösa och icke-interaktiva mekanismer, inklusive hanterade identiteter, Visual Studio Code, Visual Studio, Azure CLI osv. 3.0.0+
Active Directory-arbetsbelastningsidentitet Autentisera med en Microsoft Entra-identitet med hjälp av en federerad användartilldelad hanterad identitet för att ansluta till SQL Database från Azure-klientmiljöer som är aktiverade för arbetsbelastningsidentitet. 5.2.0+

1 Före Microsoft.Data.SqlClient 2.0.0 Active Directory Integratedoch Active Directory Interactive autentiseringslägen stöds endast i .NET Framework.

Använda lösenordsautentisering

Active Directory Password autentiseringsläge stöder autentisering till Azure-datakällor med Microsoft Entra-ID för interna eller federerade Microsoft Entra-användare. När du använder det här läget måste användarautentiseringsuppgifter anges i anslutningssträngen. I följande exempel visas hur du använder Active Directory Password autentisering.

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

Använda integrerad autentisering

Om du vill använda Active Directory Integrated autentiseringsläge måste du ha en lokal Active Directory-instans som är ansluten till Microsoft Entra-ID i molnet. Du kan till exempel federera med hjälp av Active Directory Federation Services (AD FS).

När du är inloggad på en domänansluten dator kan du komma åt Azure SQL-datakällor utan att behöva ange autentiseringsuppgifter i det här läget. Du kan inte ange användarnamn och lösenord i anslutningssträngen för .NET Framework-program. Användarnamn är valfritt i anslutningssträngen för .NET Core- och .NET Standard-program. Du kan inte ange egenskapen Credential för SqlConnection i det här läget.

Följande kodfragment är ett exempel på när Active Directory Integrated autentisering används.

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

Använda interaktiv autentisering

Active Directory Interactive autentisering stöder multifaktorautentiseringsteknik för att ansluta till Azure SQL-datakällor. Om du anger det här autentiseringsläget i anslutningssträngen visas en Azure-autentiseringsskärm och användaren uppmanas att ange giltiga autentiseringsuppgifter. Du kan inte ange lösenordet i anslutningssträngen.

Du kan inte ange egenskapen Credential för SqlConnection i det här läget. Med Microsoft.Data.SqlClient 2.0.0 och senare tillåts användarnamnet i anslutningssträngen när du är i interaktivt läge.

I följande exempel visas hur du använder Active Directory Interactive autentisering.

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

Använda autentisering med tjänsthuvudnamn

I Active Directory Service Principal autentiseringsläge kan klientprogrammet ansluta till Azure SQL-datakällor genom att ange klient-ID och hemlighet för en tjänsthuvudnamnsidentitet. Autentisering med tjänstehuvudnamn omfattar:

  1. Konfigurera en appregistrering med en hemlighet.
  2. Bevilja behörigheter till appen i Azure SQL Database-instansen.
  3. Ansluta med rätt autentiseringsuppgifter.

I följande exempel visas hur du använder Active Directory Service Principal autentisering.

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

Använda autentisering med enhetskodflöde

Med Microsoft Authentication Library för .NET (MSAL.NET) gör Active Directory Device Code Flow autentisering att klientprogrammet kan ansluta till Azure SQL-datakällor från enheter och operativsystem som inte har någon interaktiv webbläsare. Interaktiv autentisering utförs på en annan enhet. Mer information om autentisering av enhetskodflöde finns i OAuth 2.0 Device Code Flow.

När det här läget används kan du inte ange egenskapen Credential för SqlConnection. Användarnamnet och lösenordet får inte heller anges i anslutningssträngen.

Följande kodfragment är ett exempel på hur du använder Active Directory Device Code Flow autentisering.

Anmärkning

Tidsgränsen för Active Directory Device Code Flow har standardvärdet från anslutningens Connect Timeout-inställning. Se till att du anger en Connect Timeout som ger tillräckligt med tid för att kunna genomföra autentiseringsprocessen via enhetskodflödet.

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

Använda hanterad identitetsautentisering

Autentisering med hanterade identiteter för Azure-resurser är den rekommenderade autentiseringsmetoden för programmatisk åtkomst till SQL. Ett klientprogram kan använda den systemtilldelade eller användartilldelade hanterade identiteten för en resurs för att autentisera till SQL med Microsoft Entra-ID genom att ange identiteten och använda den för att hämta åtkomsttoken. Den här metoden eliminerar behovet av att hantera autentiseringsuppgifter och hemligheter och kan förenkla åtkomsthanteringen.

Det finns två typer av hanterade identiteter:

  • Systemtilldelad hanterad identitet skapas som en del av en Azure-resurs (till exempel din SQL-hanterade instans eller den logiska servern) och delar resursens livscykel. Systemtilldelade identiteter kan bara associeras med en enda Azure-resurs.
  • Användartilldelad hanterad identitet skapas som en fristående Azure-resurs. Den kan tilldelas till en eller flera instanser av en Azure-tjänst.

Mer information om hanterade identiteter finns i Om hanterade identiteter för Azure-resurser.

Eftersom Microsoft.Data.SqlClient 2.1.0 stöder drivrutinen autentisering till Azure SQL Database, Azure Synapse Analytics och Azure SQL Managed Instance genom att hämta åtkomsttoken via hanterad identitet. Om du vill använda den här autentiseringen anger du antingen Active Directory Managed Identity eller Active Directory MSI i anslutningssträngen och inget lösenord krävs. Du kan inte heller ange egenskapen Credential för SqlConnection i det här läget.

För en användartilldelad hanterad identitet måste klient-ID för den hanterade identiteten anges när du använder Microsoft.Data.SqlClient v3.0 eller senare. Om du använder Microsoft.Data.SqlClient v2.1 måste objekt-ID för den hanterade identiteten anges.

I följande exempel visas hur du använder Active Directory Managed Identity autentisering med en systemtilldelad hanterad identitet.

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

I följande exempel demonstreras Active Directory Managed Identity autentisering med en användartilldelad hanterad identitet med Microsoft.Data.SqlClient v3.0 från och med.

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

Följande exempel visar Active Directory Managed Identity autentisering med en användartilldelad hanterad identitet med 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();
}

Använda standardautentisering

Det här autentiseringsläget är tillgängligt från och med version 3.0 och ökar möjligheterna till användarautentisering. Det här läget utökar inloggningslösningarna till klientmiljön, Visual Studio Code, Visual Studio, Azure CLI osv.

Med det här autentiseringsläget hämtar drivrutinen en token genom att skicka "DefaultAzureCredential" från Azure Identity-biblioteket för att hämta en åtkomsttoken. Detta läge försöker använda olika typer av autentiseringsuppgifter för att hämta en åtkomsttoken i ordning. Beroende på vilken version av Azure Identity-biblioteket som används varierar autentiseringsuppsättningen. Versionsspecifika skillnader anges i listan. Information om azure-identitetsversionsspecifikt beteende finns i Azure.Identity API-dokument.

Viktigt!

Active Directory Default är ett praktiskt alternativ för att förenkla skillnaderna i anslutningssträngar mellan olika miljöer. Det kan dock komma med prestandaeffekter eftersom det måste söka på flera platser efter autentiseringsinformation. Om du ser långsamma anslutningshastigheter med Active Directory Default använder du ett annat autentiseringsalternativ som specifikt riktar sig mot den autentiseringsmetod som du använder i din miljö. "Active Directory Default" rekommenderas inte för miljöer som har strikta svarstider på servicenivå.

  • MiljöCredential
    • Aktiverar autentisering med Microsoft Entra-ID med hjälp av klient och hemlighet, användarnamn och lösenord, information som konfigurerats i följande miljövariabler: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Mer information)
  • WorkloadIdentityCredential
    • Aktiverar Microsoft Entra-arbetsbelastnings-ID-autentisering på Kubernetes och andra värdar som stöder arbetsbelastningsidentitet. Mer information finns i Microsoft Entra Workload ID. Tillgänglig från och med Azure Identity version 1.10 och Microsoft.Data.SqlClient 5.1.4.
  • HanteradIdentitetsautentisering
    • Försöker autentisering med Microsoft Entra-ID med hjälp av en hanterad identitet som har tilldelats distributionsmiljön. "Klient-ID" för "Användartilldelad hanterad identitet" hämtas från anslutningsegenskapen "Användar-ID".
  • SharedTokenCacheCredential
    • Autentiserar med hjälp av token i den lokala cachen som delas mellan Microsoft-program.
  • VisualStudioCredential (på engelska)
    • Aktiverar autentisering med Microsoft Entra-ID med data från Visual Studio
  • VisualStudioCodeCredential
    • Aktiverar autentisering med Microsoft Entra-ID med hjälp av data från Visual Studio Code.
  • AzurePowerShellCredential
    • Aktiverar autentisering med Microsoft Entra-ID med hjälp av Azure PowerShell. Tillgänglig från och med Azure Identity version 1.6 och Microsoft.Data.SqlClient 5.0.
  • AzureCliCredential
    • Aktiverar autentisering med Microsoft Entra-ID med hjälp av Azure CLI för att hämta en åtkomsttoken.
  • AzureDeveloperCliCredential
    • Aktiverar autentisering till Microsoft Entra-ID med hjälp av Azure Developer CLI för att hämta en åtkomsttoken. Tillgänglig från och med Azure Identity version 1.10 och Microsoft.Data.SqlClient 5.1.4.

Anmärkning

InteractiveBrowserCredential är inaktiverat i drivrutinsimplementeringen av Active Directory Default och Active Directory Interactive är det enda tillgängliga alternativet för att hämta en token med hjälp av MFA/interaktiv autentisering.

Ytterligare anpassningsalternativ är inte tillgängliga för tillfället.

I följande exempel visas hur du använder Active Directory Förvald-autentisering.

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

Använda identitetsautentisering för arbetsbelastning

Tillgänglig från och med version 5.2, liksom med hanterade identiteter, använder arbetsbelastningsidentitet autentiseringsläge värdet av parametern User ID i anslutningssträngen som klient-ID om det anges. Men till skillnad från hanterad identitet använder WorkloadIdentityCredentialOptions standardvärdet från miljövariabler: AZURE_TENANT_ID, AZURE_CLIENT_ID och AZURE_FEDERATED_TOKEN_FILE. Men endast klient-ID:t kan åsidosättas av anslutningssträngen.

I följande exempel visas Active Directory Workload Identity autentisering med en användartilldelad hanterad identitet med Microsoft.Data.SqlClient v5.2 och senare.

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

Anpassa Microsoft Entra-autentisering

Förutom att använda Microsoft Entra-autentiseringen som är inbyggd i drivrutinen ger Microsoft.Data.SqlClient 2.1.0 och senare program möjlighet att anpassa Microsoft Entra-autentisering. Anpassningen baseras på klassen ActiveDirectoryAuthenticationProvider, som härleds från den SqlAuthenticationProvider abstrakta klassen.

Under Microsoft Entra-autentisering kan klientprogrammet definiera sin egen ActiveDirectoryAuthenticationProvider-klass genom att antingen:

  • Använda en anpassad återanropsmetod.
  • Skicka ett programklient-ID till MSAL-biblioteket via SqlClient-drivrutinen för att hämta åtkomsttoken.

I följande exempel visas hur du använder ett anpassat återanrop när Active Directory Device Code Flow autentisering används.

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

Med en anpassad ActiveDirectoryAuthenticationProvider-klass kan ett användardefinierat programklient-ID skickas till SqlClient när ett Microsoft Entra-autentiseringsläge som stöds används. Microsoft Entra-autentiseringslägen som stöds omfattar Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principaloch Active Directory Device Code Flow.

Programklient-ID:t kan också konfigureras via SqlAuthenticationProviderConfigurationSection eller SqlClientAuthenticationProviderConfigurationSection. Konfigurationsegenskapen applicationClientId gäller för .NET Framework 4.6+ och .NET Core 2.1+.

Följande kodfragment är ett exempel på hur du använder en anpassad ActiveDirectoryAuthenticationProvider-klass med ett användardefinierat programklient-ID när Active Directory Interactive autentisering används.

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

I följande exempel visas hur du anger ett programklient-ID via ett konfigurationsavsnitt.

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

Använda AccessTokenCallback

Finns från och med version 5.2 en ny AccessTokenCallback-egenskap i SqlConnection. Använd egenskapen AccessTokenCallback för att definiera en anpassad funktion som returnerar en åtkomsttoken med hjälp av de inkommande parametrarna. Det är bättre att använda återanropet än att använda egenskapen AccessToken eftersom det gör att åtkomsttoken kan uppdateras i en anslutningspool. När du använder egenskapen AccessToken kan token inte uppdateras när anslutningen har öppnats. Det finns inte heller något associerat förfallodatum som anges via egenskapen. När token upphör att gälla misslyckas nya anslutningsbegäranden med ett serverautentiseringsfel och pooler som använder den måste rensas manuellt.

Viktigt!

En AccessTokenCallback måste returnera åtkomsttoken för samma säkerhetskontext för samma indataparametrar. Om säkerhetskontexten är annorlunda kan en poolanslutning med fel säkerhetskontext returneras för en anslutningsbegäran.

Anmärkning

AccessTokenCallback är en del av nyckeln som används för att identifiera anslutningspooler. Undvik att skapa ett nytt funktionsåteranrop för varje skapande av en SqlConnection eftersom det resulterar i en ny pool varje gång. Referera till samma instans av en funktion för anslutningar som ska övervägas för poolning. Nyckeln för anslutningspoolen innehåller parametrar som skickas till återanropet för att partitionera anslutningspooler på rätt sätt.

Följande kodfragment är ett exempel på hur du använder egenskapen AccessTokenCallback i Microsoft.Data.SqlClient v5.2 och senare.

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

Stöd för en anpassad SQL-autentiseringsprovider

Med större flexibilitet kan klientprogrammet också använda sin egen provider för Microsoft Entra-autentisering i stället för att använda klassen ActiveDirectoryAuthenticationProvider. Den anpassade autentiseringsprovidern måste vara en underklass av SqlAuthenticationProvider med åsidosatta metoder. Den måste sedan registrera den anpassade providern och åsidosätta en eller flera av de befintliga Active Directory* autentiseringsmetoderna.

Viktigt!

En autentiseringsprovider måste returnera åtkomsttoken för samma säkerhetskontext för samma indataparametrar. Om säkerhetskontexten är annorlunda kan en poolanslutning med fel säkerhetskontext returneras för en anslutningsbegäran.

I följande exempel visas hur du använder en ny autentiseringsleverantör för Active Directory Device Code Flow autentisering.

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

Förutom att förbättra Active Directory Interactive-autentiseringsupplevelsen tillhandahåller Microsoft.Data.SqlClient 2.1.0 och senare följande API:er för klientprogram för att anpassa interaktiv autentisering och enhetskodflödesautentisering.

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

Se även

  • Last updated on