Ověřování Microsoft Entra pomocí Microsoft.Data.SqlClient

Platí pro: .NET Framework .NET Standard

Stáhnout ADO.NET

Použijte Microsoft Entra ID k připojení bez nutnosti uložit SQL heslo ve své aplikaci. Vyberte způsob přihlášení pro hostitele, kde aplikace běží, nastavte tuto identitu v cílové databázi a udržujte zapnutou validaci certifikátů Transport Layer Security (TLS ).

Přehled

Autentizační režimy poskytované ovladačem služba Active Directory ... vyžadují jak Microsoft.Data.SqlClient, tak Microsoft.Data.SqlClient.Extensions.Azure. Nainstalujte odpovídající verze:

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

Rozšíření automaticky registruje své poskytovatele. Aplikace, které poskytují vlastní AccessToken, AccessTokenCallback, nebo poskytovatele autentizace, nepotřebují rozšíření Azure pouze pro tento účel. Přidejte knihovnu identit, kterou používá váš vlastní kód tokenu.

Před připojením:

  1. Nakonfigurujte Microsoft Entra autentizaci pro Azure SQL, nebo postupujte podle ekvivalentního nastavení vaší cílové služby.
  2. Udělit aplikaci nebo uživatelské identitě přístup k zamýšlené databázi. Získání tokenu neuděluje oprávnění k získání databáze.
  3. Povolit přístup k síti k koncovému bodu a explicitně vybrat databázi.
  4. Vyberte podporovaný autentizační režim a zpřístupněte jeho přihlašovací údaje na hostiteli aplikace.

SQL databáze v Microsoft Fabric podporuje pouze autentizaci Microsoft Entra. Nepodporuje SQL autentizaci ani SQL přihlášení. Použijte připojovací řetězec z portálu Fabric pro zamýšlený koncový bod.

Výběr režimu ověřování

Nastavte Authentication jednu z hodnot řetězce spojení v této tabulce. Sloupec vydání vám pomáhá přejít ze starších ovladačů. Současné aplikace by měly instalovat balíčky popsané v Přehledu.

Hodnota spojovacího řetězce Využití První podporované vydání
Active Directory Integrated Získejte token pomocí integrovaného ověřování systému Windows (IWA) v nakonfigurované doméně a prostředí Microsoft Entra. 1.0 na .NET Framework; 2.0 napříč podporovanými cílovými platformami.
Active Directory Interactive Přihlášení uživatelů podporující vícefaktorovou autentizaci (MFA). 1.0 na platformě .NET Framework; 2.0 napříč podporovanými cílovými platformami.
Active Directory Service Principal ID klienta aplikace a tajemství klienta. 2.0.
Active Directory Device Code Flow Přihlášení uživatele přes prohlížeč na jiném zařízení. 2.1.
služba Active Directory Managed Identity nebo služba Active Directory MSI Systémově přiřazená nebo uživatelem přiřazená spravovaná identita dostupná hostiteli aplikace. 2.1.
Active Directory Default Objevte dostupný přihlašovací list prostřednictvím řetězce přihlašovacích údajů Azure Identity. 3.0.
Active Directory Workload Identity Federovaná identita úlohy s projektovaným souborem tokenu. 5.2.
Active Directory Password Zastaralý postup přihlášení pomocí uživatelského jména a hesla. Nepoužívejte pro nové aplikace. 1.0.

Authentication=Sql Password je autentizace SQL, nikoli autentizace Microsoft Entra. Viz SQL Server a ověřování systému Windows.

Otevřete spojení

Pro konzolovou aplikaci .NET nastavte SQL_CONNECTION_STRING na příslušnou šablonu z tohoto článku po nahrazení zástupných symbolů. Tento příklad otevírá spojení a vytiskne název databáze:

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

Každý režim má jiné požadavky na hostitele. Akceptovaný parserem připojovací řetězec nedokazuje, že hostitel může získat token nebo že identita může přistupovat k databázi.

Používejte integrovanou autentizaci

služba Active Directory Integratedzískává token Microsoft Entra pomocí přihlášené doménové identity. Vyžaduje odpovídající konfiguraci spojené nebo federované identity. Není to stejné jako Integrated Security=true, který používá Windows authentication přímo se SQL Server.

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

Nezadávejte heslo ani SqlCredential. Nápověda uživatelského jména je na moderním .NET volitelná; .NET Framework pro tento režim uživatelské jméno nepřijímá. IWA nemůže splnit interaktivní MFA výzvu. Používejte interaktivní autentizaci, když nájemce vyžaduje interakci uživatele.

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

Použijte služba Active Directory Interactive pro osobu přihlašující se do desktopové nebo vývojářské aplikace. Poskytovatel autentizace uživatele vyzve a podporuje MFA. Volitelná User ID=<user_id> funkce poskytuje nápovědu k přihlášení, nikoli heslo.

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

Neposkytujte Password nebo SqlCredential. Nepoužívejte interaktivní režim pro službu bez dozoru.

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

Vestavěný režim služba Active Directory Service Principal používá ID klienta aplikace jako User ID a její tajný klíč klienta jako Password. Zadejte hlavní princip služby v databázi a udělte pouze oprávnění, která potřebuje.

Získejte tajemství z chráněné konfigurace místo toho, abyste ho vložili do zdrojového kódu. Tento příklad konzole čte hodnoty vložené do procesu:

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

Nastavte SQL_SERVER na koncový bod Transmission Control Protocol (TCP), například tcp:contoso.database.windows.net,1433, a SQL_DATABASE na název databáze. Nezaznamenávejte hodnoty prostředí ani připojovací řetězec.

Pro přihlašovací údaje založené na certifikátech získávejte tokeny pomocí ClientCertificateCredentialAccessTokenCallback. Pro federované přihlašovací údaje použijte workload identity nebo vhodný tokenový callback. Samotný režim service principal pro řetězec připojení vyžaduje klientské tajemství.

Použijte ověřování toku kódu zařízení

Tento režim použijte, když hostitel aplikace nemá prohlížeč, ale člověk se může přihlásit na jiném zařízení. Postupujte podle ověřovací URL a kódu poskytnutého autentizačním procesem.

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 omezuje ověřování; tento příklad povoluje 180 sekund. Nedoplňujte User ID, Password, nebo SqlCredential. Tok ověřování pomocí kódu zařízení stále vyžaduje přítomnost uživatele a není vhodný pro služby bez obsluhy.

Použijte ověřování pomocí spravované identity

Pro aplikaci hostovanou v Azure použijte spravovanou identitu, pokud ji hostitel podporuje. Identita patří hostiteli aplikace, nikoli automaticky databázovému serveru.

  • Systémově přiřazená spravovaná identita sdílí životní cyklus hostitelského zdroje.
  • Uživatelem přiřazená spravovaná identita je samostatný zdroj, který můžete přiřadit podporovaným hostitelům.

Pro systémově přiřazenou identitu vynechejte User ID:

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

Pro identitu přiřazenou uživatelem uveďte její ID klienta:

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

služba Active Directory MSI je kompatibilní varianta pro stejný režim. Neposkytujte heslo ani SqlCredential. Hostitel musí zpřístupnit vybranou spravovanou identitu a tato identita musí mít přístup do databáze. Vývojářská pracovní stanice nezískává spravovanou identitu použitím tohoto připojovací řetězec.

Při migraci ze SqlClient 2.1 nahraďte ID objektu uživatelem přiřazené identity jejím ID klienta. SqlClient používá ID klienta od verze 3.0.

Použijte výchozí autentizaci

služba Active Directory Defaultpoužívá řetězec přihlašovacích údajů Azure Identity k nalezení dostupné identity:

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

Kandidáti závisí na nainstalované verzi a konfiguraci Azure Identity. Patří sem přihlašovací údaje do prostředí, identita pracovní zátěže, spravovaná identita a přihlášené vývojové nástroje jako Visual Studio, Azure Command-Line Interface (CLI), Azure PowerShell a Azure Developer CLI. Viz DefaultAzureCredential pro aktuální řetězec.

SqlClient v tomto režimu deaktivuje InteractiveBrowserCredential. Zvolte služba Active Directory Interactive , zda aplikace sama potřebuje výzvu k přihlášení. Přihlašovací údaj vývojového nástroje může využít relaci navázanou při předchozím interaktivním přihlášení.

Důležité

služba Active Directory Default může zpomalit první spojení, protože DefaultAzureCredential zkouší poskytovatele přihlašovacích údajů postupně, dokud jeden neposkytne token. Nedostupní poskytovatelé mohou způsobovat prodlevy při zjišťování, v síti nebo při spouštění procesu, než se dosáhne funkčního poskytovatele. Upřednostněte v produkčním prostředí konkrétní režim ověřování, například služba Active Directory Managed Identity, služba Active Directory Workload Identity nebo služba Active Directory Service Principal, abyste se vyhnuli režijní náročnosti spojené se zjišťováním. Cachování přihlašovacích údajů a tokenů může snížit následnou akviziční práci; nepředpokládejte, že každé spojení ve skupině opakuje celý řetězec.

S služba Active Directory Default se může vybraná identita změnit při změně konfigurace hostitele.

Pro starší nasazení byly v SqlClient 5.1.4 přidány identita úlohy v rámci tohoto řetězce a podpora Azure Developer CLI. Tato funkce se liší od dedikovaného služba Active Directory Workload Identity režimu, který přišel v verzi 5.2. Podpora Azure PowerShell byla zavedena ve verzi 5.0.

Použijte ověřování pomocí identity úlohy

Použijte služba Active Directory Workload Identity na hostiteli nakonfigurovaném pro federovanou identitu úloh. Poskytovatel identity musí důvěřovat vydavateli a subjektu předpokládaného tokenu.

Osvědčení zní:

  • AZURE_TENANT_ID: identifikace nájemce.
  • AZURE_CLIENT_ID: ID klienta aplikace nebo spravované identity přiřazené uživatelem.
  • AZURE_FEDERATED_TOKEN_FILE: cesta k promítanému tokenovému souboru.
Server=tcp:contoso.database.windows.net,1433;Database=<database>;Authentication=Active Directory Workload Identity;Encrypt=true;TrustServerCertificate=false;MultiSubnetFailover=true;

Volitelný parametr User ID=<client_id> přepíše ID klienta. připojovací řetězec nepřepisuje ID tenanta ani cestu k tokenovému souboru. Nezakládejte obsah token souboru do připojovací řetězec ani logů.

Nahraďte zastaralé ověřování heslem

Důležité

Možnost ověřování ActiveDirectoryPassword (ověřování hesla Microsoft Entra ID) je v ovladačích MICROSOFT SQL zastaralá. Tento tok ověřování s vysokým rizikem není kompatibilní s povinným Microsoft Entra vícefaktorovým ověřováním (MFA) a nemusí fungovat v tenantech, ve kterých se vynucuje vícefaktorové ověřování. Naplánujte migraci na jinou metodu ověřování Microsoft Entra.

Ověřování heslem v Microsoft Entra ID je založeno na grantu OAuth 2.0 Resource Owner Password Credentials (ROPC), který umožňuje aplikaci přihlásit uživatele tím, že přímo pracuje s jeho heslem.

Microsoft doporučuje nepoužívat tok ROPC, protože není kompatibilní s vícefaktorovým ověřováním. Ve většině scénářů jsou k dispozici a doporučeny bezpečnější alternativy. Tento tok vyžaduje vysokou míru důvěryhodnosti v aplikaci a nese rizika, která nejsou přítomna v jiných tocích. Tento tok používejte pouze tehdy, pokud bezpečnější toky nejsou proveditelné. Microsoft odchází od tohoto vysoce rizikového toku ověřování, aby chránil uživatele před škodlivými útoky. Další informace najdete v tématu Plánování povinného vícefaktorového ověřování pro Azure.

Pokud je při přihlašování přítomen uživatel, použijte ověřování ActiveDirectoryInteractive nebo ActiveDirectoryIntegrated, aby byla auditní stopa přiřazena přihlášenému uživateli a aby se uplatnily zásady podmíněného přístupu.

V případě bezobslužných scénářů mezi službami postupujte podle pokynů k účtu služby Microsoft Entra:

  • Pokud vaše aplikace běží na Azure infrastruktuře, použijte ActiveDirectoryMSI (nebo ActiveDirectoryManagedIdentity v některých ovladačích). Spravované identity eliminují režii při údržbě a obměně tajných kódů a certifikátů.
  • Pokud spravovaná identita není dostupná (například aplikace běží mimo Azure), použijte ActiveDirectoryServicePrincipal. Pokud ho ovladač podporuje, upřednostňujte klientský certifikát před tajným klíčem klienta. S certifikátem zůstane privátní klíč v klientovi a do Microsoft Entra k ověření klienta se odešle jenom podepsaný kontrolní výraz. Pokud je klíč uložen v hardwaru (například v modulu TPM nebo HSM) nebo je označen jako neexportovatelný, nelze jej zkopírovat jako textový řetězec tak, jako to lze u tajného klíče klienta.
  • Nepoužívejte Microsoft Entra uživatelský účet jako účet služby.

služba Active Directory Password používá tok přihlašovacích údajů pro správce zdroje a nesplňuje požadavky MFA. Odpovídající SqlAuthenticationMethod.ActiveDirectoryPassword enum člen je zastaralý. Vyberte interaktivní autentizaci pro uživatele, spravovanou identitu, identitu pracovní zátěže nebo aplikační přihlašovací údaje pro služby.

Přizpůsobte autentizaci Microsoft Entra

Vyberte si nejmenší úpravu, která splňuje vaše požadavky, z následujících programovacích rozhraní (API):

Requirement API
Dodat již získaný žeton. SqlConnection.AccessToken.
Získávejte a obnovujte tokeny s přihlašovacím oprávněním zvoleným aplikací. SqlConnection.AccessTokenCallback.
Přizpůsobte prezentaci kódu zařízení nebo interaktivní přihlášení. ActiveDirectoryAuthenticationProvider z rozšíření Azure.
Implementujte poskytovatele autentizace ovladačů. Odvoďte z SqlAuthenticationProvider a zaregistrujte poskytovatele.

S vlastním ActiveDirectoryAuthenticationProvider, můžete zadat ID klienta aplikace, nastavit zpětné volání kódu zařízení nebo autorizačního kódu a nastavit rodičovské okno pro interaktivní přihlášení tam, kde je to podporováno. Použijte odkaz na API poskytovatele pro podpisy nainstalovaného balíčku rozšíření.

Přímo poskytněte přístupový token

Nastavte SqlConnection.AccessToken před otevřením připojení. Základní ovladač podporuje tuto vlastnost bez rozšíření Azure.

Literální token je součástí klíče poolu spojení. Jiný žeton vytváří jiný pool. SqlClient nepřijímá přes tuto vlastnost čas expirace a nemůže vám token obnovit. Získejte platný token pro nová připojení a vymažte postižené pooly, když tokeny vyprší, zvlášť pokud nastavíte nenulovou Min Pool Sizehodnotu.

Nekombinujte User ID s Password, integrovaným zabezpečením, SqlCredential nebo AccessTokenCallback, SspiContextProvider, Authentication nebo AccessToken. Nikdy nezaznamenávejte token.

Použijte AccessTokenCallback

Použijte AccessTokenCallback, když vaše aplikace sama získává tokeny a používá sdružování připojení. Callback vrací token a jeho dobu expirace, aby SqlClient mohl požádat o obnovení pro pooled authentication. API je dostupné od SqlClient 5.2.

Znovu použijte stejný instanci delegáta a objekt přihlašovacích údajů pro spojení, která by měla sdílet pool. Delegát zpětného volání je součástí klíče poolu. Vytvoření nového uzavření pro každé spojení může vytvořit samostatný pool pro každé z nich.

Důležité

Vraťte stejný bezpečnostní kontext pro stejné vstupy zpětného volání. Nevybírejte jiného uživatele ze stavu ambientního požadavku uvnitř sdíleného callbacku. Připojení z fondu by jinak mohlo být vráceno s nesprávnou identitou.

Tento příklad .NET konzole používá přihlášenou identitu Azure CLI pro lokální vývoj. Nainstalujte Microsoft.Data.SqlClient a Azure.Identity, přihlaste se do Azure CLI pomocí identity, která má přístup k databázi, a nastavte SQL_SERVER a SQL_DATABASE. Pro tento příklad není potřeba rozšíření Azure.

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

Pro produkci nahraďte AzureCliCredential zamýšlenou kvalifikací, například ManagedIdentityCredential, WorkloadIdentityCredential, nebo ClientCertificateCredential, a nastavte její předpoklady. Neměňte identitu sdíleného callbacku, dokud jsou jeho spojení stále dostupná.

Nekombinujte AccessTokenCallback s Authentication, integrovanou bezpečností, AccessToken, nebo SspiContextProvider. Callback může použít User ID jako selektor identity, ale váš callback jej musí konzistentně interpretovat. Příklad nepoužívá selektor, protože má jeden pevně daný přihlašovací údaj.

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

Odvoďte ji z SqlAuthenticationProvider, implementujte její rozhraní pro získávání tokenů a zaregistrujte ji v SqlAuthenticationProvider.SetProvider pro autentizační metodu, kterou nahrazujete. Registrujte poskytovatele při inicializaci aplikace, před otevřením spojení.

Poskytovatel musí vrátit platný token a čas expirace požadovaného zdroje a oprávnění. Stejné pravidlo bezpečnostního kontextu, které se používá pro callbacky, platí i pro poskytovatele. Přepsání poskytovatele neodstraní požadavky cílové služby na identitu, tenanta ani oprávnění k databázi.

Migrace na Microsoft.Data.SqlClient 7.0

Aplikace upgradující napříč rozdělením balíčků by měly přezkoumat závislosti a autentizační konfiguraci.

Co se změnilo ve verzi 7.0

Základní ovladač již nezahrnuje autentizační závislosti Azure a Microsoft Entra. ActiveDirectoryAuthenticationProvider Vestavěný se přesouvá do Microsoft.Data.SqlClient.Extensions.Azure, přičemž sdílené kontrakty jsou v Microsoft.Data.SqlClient.Extensions.Abstractions.

Krok 1: Instalace balíčku rozšíření Azure

U režimů Microsoft Entra poskytovaných ovladačem nainstalujte odpovídající verze jádra a rozšíření Azure, jak je uvedeno v Overview. Nasaďte rozšíření společně s aplikací. Pro vestavěné režimy není vyžadována manuální registrace poskytovatele.

Krok 2: Nahrazení zastaralých režimů ověřování

Nahraďte služba Active Directory Password to režimem, který odpovídá uživatelskému interakčnímu a hostingovému modelu vaší aplikace. Pro nasazení bez dozoru zvolte konkrétní identitu pracovní zátěže místo spoléhání se na přihlášení vývojáře.

Krok 3: Kontrola připojovacích řetězců

Pokud stávající podporovaná hodnota Authentication stále vyhovuje nasazení, zachovejte ji. Potvrďte název databáze, výběr identity, nastavení šifrování a přístup do sítě. Nepřidávejte Integrated Security=true do Microsoft Entra připojovací řetězec.

Aplikace, které nepoužívají ověřování Entra ID

SQL heslo a integrovaná autentizace ve Windows nevyžadují rozšíření Azure. Aplikace, které si již samy získávají vlastní tokeny, mohou i nadále používat AccessToken nebo AccessTokenCallback s hlavním ovladačem a zvolenou knihovnou identit.

Související obsah

  • Poslední aktualizace v