Microsoft Entra-authenticatie met Microsoft. Data.SqlClient

Van toepassing op: .NET Framework .NET Standard

ADO.NET downloaden

Gebruik Microsoft Entra ID om verbinding te maken zonder een SQL-wachtwoord in je applicatie op te slaan. Kies een aanmeldmethode voor de host waar de applicatie draait, stel die identiteit in de doeldatabase in en houd Transport Layer Security (TLS) certificaatvalidatie ingeschakeld.

Overzicht

De door de bestuurder geleverde Active Directory ... authenticatiemodi vereisen zowel Microsoft.Data.SqlClient als Microsoft.Data.SqlClient.Extensions.Azure. Installeer overeenkomende versies:

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

De extensie registreert haar aanbieders automatisch. Applicaties die hun eigen AccessToken, AccessTokenCallback of authenticatieprovider gebruiken, hebben de Azure-extensie niet uitsluitend daarvoor nodig. Voeg de identiteitsbibliotheek toe die door je eigen token-code wordt gebruikt.

Voordat je aansluit:

  1. Configureer Microsoft Entra-authenticatie voor Azure SQL, of volg de equivalente setup van je doeldienst.
  2. Verleen de applicatie of gebruikersidentiteit toegang tot de beoogde database. Het verkrijgen van een token geeft geen databaserechten.
  3. Sta netwerktoegang tot het eindpunt toe en selecteer expliciet de database.
  4. Kies een ondersteunde authenticatiemodus en maak de inloggegevens beschikbaar op de applicatiehost.

SQL-database in Microsoft Fabric ondersteunt alleen Microsoft Entra-authenticatie. Het ondersteunt geen SQL-authenticatie of SQL-logins. Gebruik de verbindingsreeks van het Fabric-portaal voor het beoogde eindpunt.

Een verificatiemodus kiezen

Stel Authentication in op een van de verbindingsstringwaarden in deze tabel. De releasekolom helpt je om over te stappen van oudere stuurprogramma's. Huidige applicaties moeten de pakketten installeren die in Overzicht worden beschreven.

Verbindingsstringwaarde Gebruik Eerste ondersteunde release
Active Directory Integrated Verkrijg een token door gebruik te maken van geïntegreerde Windows-authenticatie (IWA) in een geconfigureerd domein en een Microsoft Entra-omgeving. 1.0 op het .NET Framework; 2.0 over ondersteunde doelen.
Active Directory Interactive Gebruikersaanmelding die multifactorauthenticatie (MFA) ondersteunt. 1.0 op het .NET Framework; 2.0 over ondersteunde doelen.
Active Directory Service Principal Client-ID van de applicatie en clientgeheim. 2.0.
Active Directory Device Code Flow Gebruiker meldt zich aan via een browser op een ander apparaat. 2.1.
Active Directory Managed Identity of Active Directory MSI Systeem- of door de gebruiker toegewezen beheerde identiteit is beschikbaar voor de applicatiehost. 2.1.
Active Directory Default Ontdek een beschikbare referentie in een referentieketen van Azure Identity. 3.0.
Active Directory Workload Identity Gefedereerde werklastidentiteit met een geprojecteerd tokenbestand. 5.2.
Active Directory Password Verouderde gebruikersnaam/wachtwoord-flow. Gebruik het niet voor nieuwe applicaties. 1.0.

Authentication=Sql Passwordis SQL-authenticatie, niet Microsoft Entra-authenticatie. Zie SQL Server en Windows authentication.

Open een verbinding

Voor een .NET-consoletoepassing stelt u SQL_CONNECTION_STRING nadat u de placeholders hebt vervangen in op het juiste sjabloon uit dit artikel. Dit voorbeeld opent de verbinding en print de databasenaam:

using Microsoft.Data.SqlClient;

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

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

Elke modus heeft verschillende vereisten voor de host. Een door de parser geaccepteerde verbindingsreeks bewijst niet dat de host een token kan verkrijgen of dat de identiteit toegang heeft tot de database.

Gebruik geïntegreerde authenticatie

Active Directory Integratedverkrijgt een Microsoft Entra-token door gebruik te maken van de ingelogde domeinidentiteit. Het vereist de juiste gekoppelde of gefedereerde identiteitsconfiguratie. Het is niet hetzelfde als Integrated Security=true, dat Windows authentication direct gebruikt met SQL Server.

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

Voer geen wachtwoord of SqlCredential in. Een gebruikersnaamtip is optioneel in modern .NET; .NET Framework accepteert geen gebruikersnaam voor deze modus. IWA kan niet voldoen aan een interactieve MFA-uitdaging. Gebruik interactieve authenticatie wanneer de tenant gebruikersinteractie vereist.

Interactieve verificatie gebruiken

Gebruik Active Directory Interactive voor iemand die zich aanmeldt bij een desktop- of ontwikkelaarstoepassing. De authenticatieprovider vraagt de gebruiker om invoer en ondersteunt MFA. Een optionele User ID=<user_id> geeft een aanmeldhint, geen wachtwoord.

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

Geef Password of SqlCredential niet op. Gebruik geen interactieve modus voor een onbemand dienst.

Gebruik serviceprincipal-verificatie

De ingebouwde Active Directory Service Principal modus gebruikt de client-ID van een applicatie als User ID en het clientgeheim als Password. Richt de service-principal in de database in en verleen alleen de machtigingen die deze nodig heeft.

Haal het geheim op uit een beschermde configuratie in plaats van het in de bron in te sluiten. Dit voorbeeld van de console leest waarden die in het proces zijn geïnjecteerd:

using Microsoft.Data.SqlClient;

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

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

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

Stel SQL_SERVER in op je Transmission Control Protocol (TCP)-eindpunt, zoals tcp:contoso.database.windows.net,1433, en SQL_DATABASE op de databasenaam. Registreer de omgevingswaarden of de verbindingsreeks niet.

Voor certificaatgebaseerde applicatiegegevens, verkrijg tokens via ClientCertificateCredentialAccessTokenCallback. Voor gefedereerde inloggegevens gebruik je workload identity of een geschikte token callback. De verbindingsstring-service principal-modus vereist zelf een clientgeheim.

Gebruik apparaatcode-flowauthenticatie

Gebruik deze modus wanneer de applicatiehost geen browser heeft, maar iemand wel op een ander apparaat kan inloggen. Volg de verificatie-URL en code die door de authenticatieflow worden verstrekt.

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

Connect Timeout grensauthenticatie; dit voorbeeld staat 180 seconden toe. Lever User ID, Password of SqlCredential niet. De codeflow van het apparaat vereist nog steeds een persoon en is ongeschikt voor onbemand werk.

Gebruik verificatie van beheerde identiteit

Voor een door Azure gehoste applicatie gebruik je een beheerde identiteit wanneer de host deze ondersteunt. De identiteit behoort toe aan de applicatiehost, niet automatisch aan de databaseserver.

  • Een door het systeem toegewezen beheerde identiteit deelt de levenscyclus van de hostresource.
  • Een door de gebruiker toegewezen beheerde identiteit is een aparte resource die je kunt toewijzen aan ondersteunde hosts.

Voor een systeem-toegewezen identiteit, laat het volgende weg:User ID

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

Voor een door de gebruiker toegewezen identiteit geef je het client-ID in:

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

Active Directory MSI is een compatibiliteitsspelling voor dezelfde modus. Vul geen wachtwoord of SqlCredential in. De host moet de geselecteerde beheerde identiteit blootstellen, en die identiteit moet database-toegang hebben. Een developer workstation krijgt geen beheerde identiteit door deze verbindingsreeks te gebruiken.

Bij migratie van SqlClient 2.1 vervang dan de door de gebruiker toegewezen object-ID door de client-ID. SqlClient gebruikt de client-ID vanaf 3.0.

Gebruik standaardauthenticatie

Active Directory Defaultgebruikt een Azure Identity-credentialketen om een beschikbare identiteit te ontdekken:

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

Kandidaten zijn afhankelijk van de geïnstalleerde versie en configuratie van Azure Identity. Deze omvatten omgevingsinloggegevens, workload-identiteit, beheerde identiteit en ingelogde ontwikkeltools zoals Visual Studio, Azure Command-Line Interface (CLI), Azure PowerShell en Azure Developer CLI. Zie DefaultAzureCredential voor de huidige keten.

SqlClient schakelt InteractiveBrowserCredential in deze modus uit. Kies Active Directory Interactive of de applicatie zelf moet vragen om inloggen. Een ontwikkeltool-credential kan een sessie gebruiken die is ingesteld door een eerdere interactieve aanmelding.

Belangrijk

Active Directory Default kan de eerste verbinding vertragen, omdat DefaultAzureCredential referentieproviders achtereenvolgens probeert totdat een ervan een token levert. Onbeschikbare aanbieders kunnen vertragingen bij ontdekking, netwerk of processtart veroorzaken voordat de werkende aanbieder wordt bereikt. Geef de voorkeur aan een specifieke authenticatiemodus in productie, zoals Active Directory Managed Identity, Active Directory Workload Identity, of Active Directory Service Principal, om deze ontdekkingsoverhead te vermijden. Credential- en tokencaching kan het werk van latere acquisitie verminderen; ga er niet van uit dat elke gepoolde verbinding de volledige keten herhaalt.

Met Active Directory Default kan de geselecteerde identiteit veranderen wanneer de hostconfiguratie wijzigt.

Voor oudere implementaties kwamen workload-identiteit binnen deze keten en Azure Developer CLI-ondersteuning in SqlClient 5.1.4. Die functie verschilt van de dedicated Active Directory Workload Identity modus, die in 5.2 verscheen. Azure PowerShell-ondersteuning arriveerde in 5.0.

Gebruik workload-identiteitsauthenticatie

Gebruik Active Directory Workload Identity op een host die is geconfigureerd voor gefedereerde workload-identiteit. De identiteitsprovider moet vertrouwen hebben in de uitgever en het subject van de geprojecteerde token.

Het certificaat luidt:

  • AZURE_TENANT_ID: de huurders-ID.
  • AZURE_CLIENT_ID: de client-ID van de toepassing of de door de gebruiker toegewezen beheerde identiteit.
  • AZURE_FEDERATED_TOKEN_FILE: het pad naar het geprojecteerde tokenbestand.
Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Workload Identity;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Een optionele User ID=<client_id> overschrijft de client-ID. De verbindingsreeks overschrijft niet de tenant-ID of het pad naar het tokenbestand. Plaats de inhoud van het tokenbestand niet in de verbindingsreeks of logboeken.

Vervang verouderde wachtwoordauthenticatie

Belangrijk

De optie ActiveDirectoryPassword-verificatie (Microsoft Entra ID wachtwoordverificatie) is afgeschaft in de Microsoft SQL-stuurprogramma's. Deze verificatiestroom met een hoog risico is niet compatibel met verplichte Microsoft Entra multifactorauthenticatie (MFA) en functioneert mogelijk niet in tenants waar MFA wordt afgedwongen. Plan om te migreren naar een andere Microsoft Entra verificatiemethode.

Microsoft Entra ID wachtwoordverificatie is gebaseerd op de OAuth 2.0 ROPC-toekenning (Resource Owner Password Credentials), waarmee een toepassing zich kan aanmelden bij de gebruiker door het wachtwoord rechtstreeks te verwerken.

Microsoft raadt u aan de ROPC-stroom niet te gebruiken omdat deze niet compatibel is met MFA. In de meeste scenario's zijn veiligere alternatieven beschikbaar en aanbevolen. Deze stroom vereist een hoge mate van vertrouwen in de toepassing en brengt risico's met zich mee die niet aanwezig zijn in andere stromen. Gebruik deze stroom alleen als veiligere stromen niet haalbaar zijn. Microsoft gaat weg van deze verificatiestroom met een hoog risico om gebruikers te beschermen tegen schadelijke aanvallen. Zie Planning voor verplichte meervoudige verificatie voor Azure voor meer informatie.

Wanneer een gebruiker aanwezig is bij het aanmelden, gebruikt u ActiveDirectoryInteractive- of ActiveDirectoryIntegrated-verificatie, zodat de kenmerken van het audittrailbeleid voor de aangemelde gebruiker en het beleid voor voorwaardelijke toegang van toepassing zijn.

Voor service-naar-servicescenario's zonder toezicht volgt u de richtlijnen voor het Microsoft Entra serviceaccount:

  • Als uw toepassing wordt uitgevoerd op Azure infrastructuur, gebruikt u ActiveDirectoryMSI (of ActiveDirectoryManagedIdentity in sommige stuurprogramma's). Beheerde identiteiten elimineren de overhead van het onderhouden en roteren van geheimen en certificaten.
  • Als beheerde identiteit niet beschikbaar is (de toepassing wordt bijvoorbeeld buiten Azure uitgevoerd), gebruikt u ActiveDirectoryServicePrincipal. Als het stuurprogramma dit ondersteunt, geef dan de voorkeur aan een clientcertificaat boven een clientgeheim. Met een certificaat blijft de persoonlijke sleutel op de client staan en wordt alleen een ondertekende assertie verzonden naar Microsoft Entra om de client te verifiëren. Als de sleutel is opgeslagen in hardware (zoals een TPM of HSM) of als niet-exporteerbaar is gemarkeerd, kan deze niet worden gekopieerd als een tekenreeks zoals een clientgeheim dat kan.
  • Gebruik geen Microsoft Entra gebruikersaccount als een serviceaccount.

Active Directory Password gebruikt de resource owner password credentials flow en kan niet voldoen aan de MFA-vereisten. Het overeenkomstige SqlAuthenticationMethod.ActiveDirectoryPassword enumlid is verouderd. Kies interactieve authenticatie voor gebruikers, of een beheerde identiteit, een workloadidentiteit of een toepassingsreferentie voor services.

Pas Microsoft Entra-authenticatie aan

Kies de kleinste aanpassing die aan uw eisen voldoet uit de volgende application programming interfaces (API's):

Requirement API
Lever een reeds verworven token. SqlConnection.AccessToken.
Verkrijg en vernieuw tokens met een door de applicatie geselecteerde credential. SqlConnection.AccessTokenCallback.
Pas de presentatie van apparaatcodes of interactieve aanmelding aan. ActiveDirectoryAuthenticationProvider uit de Azure-extensie.
Implementeer een authenticatieprovider voor stuurprogramma's. Overerv van SqlAuthenticationProvider en registreer de provider.

Met een aangepaste ActiveDirectoryAuthenticationProvider, kun je een applicatieclient-ID invoeren, apparaatcode of autorisatiecode-callbacks configureren, en het oudervenster instellen voor interactieve aanmelding waar ondersteund. Gebruik de provider-API-referentie voor de handtekeningen van het geïnstalleerde extensiepakket.

Geef direct een toegangstoken

Stel het in SqlConnection.AccessToken voordat je de verbinding opent. De kerndriver ondersteunt deze eigenschap zonder de Azure-extensie.

Het letterlijke token maakt deel uit van de connectiepool-sleutel. Een andere token creëert een andere pool. SqlClient ontvangt geen vervaldatum via deze eigenschap en kan het token niet voor je verlengen. Verkrijg een geldig toegangstoken voor nieuwe verbindingen en wis de betreffende pools wanneer tokens verlopen, vooral als je Min Pool Size op een niet-nulwaarde instelt.

Combineer AccessToken niet met User ID, geïntegreerde beveiliging, Password of SqlCredential, AccessTokenCallback, SspiContextProvider of Authentication. Log nooit een token.

Gebruik AccessTokenCallback

Geef de voorkeur AccessTokenCallback wanneer je applicatie zelf tokens verzamelt en verbinding pooling gebruikt. De callback levert een token en de vervaldatum daarvan terug, zodat SqlClient verlenging kan aanvragen voor pooled authentication. De API is beschikbaar vanaf SqlClient 5.2.

Hergebruik dezelfde delegate-instantie en credential-object voor verbindingen die een pool zouden moeten delen. De callback-delegate maakt deel uit van de poolsleutel. Het creëren van een nieuwe closure voor elke verbinding kan voor elke verbinding een aparte pool creëren.

Belangrijk

Geef dezelfde beveiligingscontext terug voor dezelfde callback-invoer. Selecteer geen andere gebruiker vanuit ambient request state binnen een gedeelde callback. Een gepoolde verbinding kan anders onder de verkeerde identiteit worden teruggegeven.

Dit .NET-consolevoorbeeld gebruikt de ingelogde Azure CLI-identiteit voor lokale ontwikkeling. Installeer Microsoft.Data.SqlClient en Azure.Identity, log in op Azure CLI met een identiteit die database-toegang heeft, en stel SQL_SERVER in en SQL_DATABASE. De Azure-extensie is voor dit voorbeeld niet vereist.

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

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

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

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

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

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

In productie vervang je AzureCliCredential door de beoogde aanmeldingsgegevens, zoals ManagedIdentityCredential, WorkloadIdentityCredential of ClientCertificateCredential, en configureer je de vereisten daarvoor. Verander de identiteit achter een gedeelde callback niet zolang de gepoolde verbindingen beschikbaar blijven.

Niet combineren AccessTokenCallback met Authentication, geïntegreerde beveiliging, AccessToken, of SspiContextProvider. Een callback kan User ID als identiteitsselector gebruiken, maar je callback moet die consistent interpreteren. Het voorbeeld gebruikt geen selector omdat het één vaste credential heeft.

Ondersteuning voor een aangepaste SQL-verificatieprovider

Leid af van SqlAuthenticationProvider, implementeer het token-acquisitiecontract en registreer het met SqlAuthenticationProvider.SetProvider voor de authenticatiemethode die je vervangt. Registreer providers tijdens de initialisatie van de applicatie, voordat je verbindingen opent.

De provider moet een geldig token en vervaldatum voor de gevraagde resource en autoriteit teruggeven. Dezelfde beveiligingscontextregel die wordt gebruikt voor callbacks geldt voor providers. Het overschrijven van een provider verwijdert niet de vereisten voor de identiteit, tenant of databasemachtigingen van de doeldienst.

Migreren naar Microsoft.Data.SqlClient 7.0

Applicaties die upgraden over de package split moeten afhankelijkheden en authenticatieconfiguraties bekijken.

Wat is er veranderd in 7.0

De kerndriver brengt geen Azure- en Microsoft Entra-authenticatieafhankelijkheden meer mee. De ingebouwde ActiveDirectoryAuthenticationProvider wordt verplaatst naar Microsoft.Data.SqlClient.Extensions.Azure, met gedeelde contracten in Microsoft.Data.SqlClient.Extensions.Abstractions.

Stap 1: Het Azure-extensiepakket installeren

Voor door drivers geleverde Microsoft Entra-modi installeer je de overeenkomende core- en Azure-extensieversies zoals weergegeven in Overzicht. Implementeer de extensie samen met de applicatie. Voor de ingebouwde modi is geen handmatige zorgverlenerregistratie vereist.

Stap 2: afgeschafte verificatiemodi vervangen

Vervang Active Directory Password door een modus die past bij het gebruikersinteractie- en hostingmodel van je applicatie. Voor een onbemande implementatie kies je een specifieke workload-identiteit in plaats van te vertrouwen op de aanmelding van een ontwikkelaar.

Stap 3: Controleren van verbindingsreeksen

Houd de bestaande ondersteunde Authentication waarde als die nog steeds bij de implementatie past. Bevestig de databasenaam, identiteitsselector, encryptie-instellingen en netwerktoegang. Voeg niet toe Integrated Security=true aan een Microsoft Entra verbindingsreeks.

Toepassingen die geen Entra ID-verificatie gebruiken

SQL-wachtwoord en Windows-geïntegreerde authenticatie vereisen de Azure-extensie niet. Applicaties die al hun eigen tokens ophalen, kunnen met de basisdriver en de door hen gekozen identiteitsbibliotheek gebruik blijven maken van AccessToken of AccessTokenCallback.

Verwante onderwerpen

  • Laatst bijgewerkt om