Megosztás a következőn keresztül:

Csatlakozás az Azure SQL-hez Microsoft Entra-hitelesítéssel és SqlClient-lel

A következőkre vonatkozik: .NET keretrendszer .NET .NET szabvány

ADO.NET letöltése

Ez a cikk azt ismerteti, hogyan csatlakozhat Azure SQL-adatforrásokhoz Microsoft Entra-hitelesítéssel egy .NET alkalmazásból az SqlClient használatával.

Megjegyzés:

Bár a Microsoft Entra ID az Azure Active Directory (Azure AD) új neve, a meglévő környezetek megzavarásának megakadályozása érdekében az Azure AD továbbra is megmarad néhány kódoltan rögzített elemben, például a felhasználói felület mezőiben, kapcsolatszolgáltatókban, hibakódokban és parancsmagokban. Ebben a cikkben a két név felcserélhető.

Áttekintés

A Microsoft Entra-hitelesítés a Microsoft Entra ID identitásait használja az olyan adatforrások eléréséhez, mint a Azure SQL Database, az Azure SQL Managed Instance és a Azure Synapse Analytics. A Microsoft.Data.SqlClient névtér lehetővé teszi az ügyfélalkalmazások számára, hogy a Microsoft Entra hitelesítő adatait különböző hitelesítési módokban adják meg, amikor csatlakoznak az Azure SQL Database és Azure SQL Managed Instance-hoz. A Microsoft Entra hitelesítés Azure SQL-lel való használatához konfigurálnia és kezelnie kell a Microsoft Entra-hitelesítést az Azure SQL-lel.

Amikor beállítja a kapcsolat tulajdonságot Authentication a kapcsolati sztringben, az ügyfél a megadott értéknek megfelelően kiválaszthatja az előnyben részesített Microsoft Entra hitelesítési módot:

  • A legkorábbi Microsoft.Data.SqlClient verzió támogatja a .NET Framework, a .NET Core és a .NET Standard verziót Active Directory Password . A .NET-keretrendszer Active Directory Integrated hitelesítését és Active Directory Interactive hitelesítését is támogatja.

  • A Microsoft.Data.SqlClient 2.0.0-s verziójától kezdődően a Active Directory Integrated és a Active Directory Interactive típusú hitelesítés támogatása kiterjed a .NET Framework, a .NET Core és a .NET Standard környezetekre.

    Az SqlClient 2.0.0-s verzióban egy új Active Directory Service Principal hitelesítési mód is hozzá van adva. Hitelesítéshez egy szolgáltatási főazonosító ügyfél-ID-jét és titkos kulcsát használja.

  • A Microsoft.Data.SqlClient 2.1.0 további hitelesítési módokat ad hozzá, beleértve a Active Directory Device Code Flow és ( Active Directory Managed Identity más néven Active Directory MSI). Ezek az új módok lehetővé teszik, hogy az alkalmazás hozzáférési jogkivonatot szerezzen be a kiszolgálóhoz való csatlakozáshoz.

A következő szakaszokban ismertetett Microsoft Entra-hitelesítéssel kapcsolatos információkért lásd: Microsoft Entra-hitelesítés használata.

Microsoft Entra hitelesítés beállítása

Ha az alkalmazás Microsoft Entra-hitelesítéssel csatlakozik Azure SQL-adatforrásokhoz, érvényes hitelesítési módot kell biztosítania. Az alábbi táblázat felsorolja a támogatott hitelesítési módokat. Az alkalmazás a Authentication kapcsolati tulajdonságot használva határoz meg egy módot a kapcsolati sztringben.

Érték Leírás Microsoft.Data.SqlClient verzió
Active Directory-jelszó Hitelesítés Microsoft Entra-identitás felhasználónevével és jelszavával 1.0+
Integrált Active Directory Hitelesítés Microsoft Entra-identitással integrált Windows-hitelesítés (IWA) használatával 2.0.0+1
Active Directory Interaktív Hitelesítés Microsoft Entra-identitással interaktív hitelesítéssel 2.0.0+1
Active Directory szolgáltatásnév Hitelesítés egy Microsoft Entra szolgáltatásfiókkal az ügyfélazonosító és a titok használatával 2.0.0+
Active Directory eszközkód-áramlás Hitelesítés Microsoft Entra-identitással eszközkódfolyam módban 2.1.0+
Active Directory felügyelt identitás,
Active Directory MSI		 Hitelesítés Microsoft Entra rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitással 2.1.0+
Active Directory alapértelmezett beállítás Hitelesítés Microsoft Entra-identitással jelszó nélküli és nem interaktív mechanizmusokkal, például felügyelt identitásokkal, Visual Studio Code-dal, Visual Studióval, Azure CLI-vel stb. 3.0.0+
Active Directory számítási feladat identitása Hitelesítés Microsoft Entra-identitással egy összevont, felhasználó által hozzárendelt felügyelt identitással a számítási feladatok identitásához engedélyezett Azure-ügyfélkörnyezetekből való SQL Database-hez való csatlakozáshoz. 5.2.0+

1 A Microsoft.Data.SqlClient 2.0.0Active Directory Integrated előtt a Active Directory Interactive hitelesítési módok csak a .NET Framework esetén voltak támogatottak.

Jelszó-hitelesítés használata

Active Directory Password A hitelesítési mód támogatja az Azure-adatforrások hitelesítését Microsoft Entra azonosítóval a natív vagy összevont Microsoft Entra felhasználók számára. Ha ezt a módot használja, a felhasználói hitelesítő adatokat meg kell adni a kapcsolati sztringben. Az alábbi példa bemutatja, hogyan kell használni Active Directory Password a hitelesítést.

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

Integrált hitelesítés használata

A hitelesítési mód használatához Active Directory Integrated rendelkeznie kell egy helyi Active Directory-példánnyal, amely csatlakozik a Microsoft Entra azonosítóhoz a felhőben. Az összevonást például az Active Directory összevonási szolgáltatások (AD FS) használatával végezheti el.

Ha bejelentkezett egy tartományhoz csatlakoztatott gépre, ebben a módban anélkül érheti el az Azure SQL-adatforrásokat, hogy hitelesítő adatokat kérne. NET-keretrendszer alkalmazások kapcsolati sztringjében nem adhat meg felhasználónevet és jelszót. A felhasználónév megadása nem kötelező a .NET Core és a .NET Standard alkalmazások kapcsolati sztringjében. Ebben a módban nem állíthatja be az Credential SqlConnection tulajdonságát.

Az alábbi kódrészlet egy példa arra, hogy mikor Active Directory Integrated van használatban a hitelesítés.

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

Interaktív hitelesítés használata

Active Directory Interactive A hitelesítés támogatja a többtényezős hitelesítési technológiát az Azure SQL-adatforrásokhoz való csatlakozáshoz. Ha ezt a hitelesítési módot adja meg a kapcsolati sztringben, megjelenik egy Azure-hitelesítési képernyő, amely érvényes hitelesítő adatok megadását kéri a felhasználótól. A jelszó nem adható meg a kapcsolati sztringben.

Ebben a módban nem állíthatja be az Credential SqlConnection tulajdonságát. A Microsoft.Data.SqlClient 2.0.0-s és újabb verzióiban a felhasználónév interaktív módban engedélyezett a kapcsolati sztringben.

Az alábbi példa bemutatja, hogyan kell használni Active Directory Interactive a hitelesítést.

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

Szolgáltatási főalany hitelesítés használata

Hitelesítési Active Directory Service Principal módban az ügyfélalkalmazás egy szolgáltatásnév-identitás ügyfél-azonosítójának és titkos kulcsának megadásával csatlakozhat az Azure SQL-adatforrásokhoz. A szolgáltatás azonosító hitelesítése a következőket foglalja magában:

  1. Alkalmazásregisztráció beállítása titkos kóddal.
  2. Engedélyek megadása az alkalmazáshoz a Azure SQL Database-példányban.
  3. Csatlakozás a megfelelő hitelesítő adattal.

Az alábbi példa bemutatja, hogyan kell használni Active Directory Service Principal a hitelesítést.

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

Eszközkódfolyam-hitelesítés használata

NET-hez készült Microsoft Authentication Library (MSAL.NET) hitelesítés lehetővé teszi, Active Directory Device Code Flow hogy az ügyfélalkalmazás olyan eszközökről és operációs rendszerekről csatlakozzon az Azure SQL-adatforrásokhoz, amelyek nem rendelkeznek interaktív webböngészővel. Az interaktív hitelesítés egy másik eszközön történik. További információ az eszközkódfolyam-hitelesítésről: OAuth 2.0 eszközkódfolyam.

Ha ez a mód használatban van, nem állíthatja be a CredentialSqlConnection tulajdonságát. Ezenkívül a felhasználónevet és a jelszót nem szabad megadni a kapcsolati sztringben.

Az alábbi kódrészlet egy példa a hitelesítés használatára Active Directory Device Code Flow .

Megjegyzés:

Az időtúllépés alapértelmezés szerint a kapcsolat Active Directory Device Code Flow beállítását használja. Ügyeljen arra, hogy olyan értéket Connect Timeout adjon meg, amely elegendő időt biztosít az eszközkódfolyam hitelesítési folyamatának végrehajtásához.

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

Felügyelt identitáshitelesítés használata

Az Azure-erőforrások felügyelt identitásokkal való hitelesítése az ajánlott hitelesítési módszer az SQL-hez való programozott hozzáféréshez. Egy ügyfélalkalmazás használhatja egy erőforrás rendszer vagy felhasználó által hozzárendelt felügyelt identitását arra, hogy a Microsoft Entra ID segítségével hitelesítse magát az SQL adatbázishoz, az identitás megadásával és hozzáférési tokenek megszerzésével. Ez a módszer szükségtelenné teszi a hitelesítő adatok és titkos kulcsok kezelését, és leegyszerűsítheti a hozzáférés-kezelést.

A felügyelt identitásoknak két típusa létezik:

  • A rendszer által hozzárendelt felügyelt identitás egy Azure-erőforrás (például a felügyelt SQL-példány vagy a logikai kiszolgáló) részeként jön létre, és megosztja az erőforrás életciklusát. A rendszer által hozzárendelt identitások csak egyetlen Azure-erőforráshoz társíthatók.
  • A felhasználó által hozzárendelt felügyelt identitás önálló Azure-erőforrásként jön létre. Hozzárendelhető egy Azure-szolgáltatás egy vagy több példányához.

További információ a felügyelt identitásokról: Az Azure-erőforrások felügyelt identitásai.

A Microsoft.Data.SqlClient 2.1.0 óta az illesztőprogram támogatja a Azure SQL Database, Azure Synapse Analytics és Azure SQL Managed Instance hitelesítését a hozzáférési jogkivonatok felügyelt identitáson keresztüli beszerzésével. A hitelesítés használatához adja meg a Active Directory Managed Identity vagy a Active Directory MSI kapcsolatot a kapcsolati sztringben, és nincs szükség jelszóra. Ebben a módban sem állíthatja be a Credential tulajdonságát SqlConnection .

Felhasználó által hozzárendelt felügyelt identitás esetén a felügyelt identitás ügyfél-azonosítóját meg kell adni a Microsoft.Data.SqlClient 3.0-s vagy újabb verzió használatakor. A Microsoft.Data.SqlClient 2.1-es verziójának használata esetén meg kell adni a felügyelt identitás objektumazonosítóját .

Az alábbi példa bemutatja, hogyan használható Active Directory Managed Identity a hitelesítés rendszer által hozzárendelt felügyelt identitással.

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

Az alábbi példa egy felhasználó által hozzárendelt felügyelt identitással való hitelesítést mutatja be Active Directory Managed Identity a Microsoft.Data.SqlClient 3.0-s verziójától kezdődően.

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

Az alábbi példa egy felhasználó által hozzárendelt felügyelt identitással való hitelesítést mutatja be Active Directory Managed Identity a Microsoft.Data.SqlClient 2.1-es verziójával.

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

Alapértelmezett hitelesítés használata

A 3.0-s verziótól kezdődően elérhető hitelesítési mód kibővíti a felhasználói hitelesítés lehetőségeit. Ez a mód kiterjeszti a bejelentkezési megoldásokat az ügyfélkörnyezetre, a Visual Studio Code-ra, a Visual Studióra, az Azure CLI-re stb.

Ezzel a hitelesítési móddal a meghajtó a "DefaultAzureCredential" átadásával szerez be egy hozzáférési tokent az Azure Identity könyvtárból. Ez a mód hitelesítőadat-típusok készletével próbálja meg sorrendben beszerezni a hozzáférési jogkivonatot. A használt Azure Identity kódtár verziójától függően a hitelesítő adatok készlete eltérő. A verzióspecifikus különbségek a listában vannak feltüntetve. Az Azure Identity verzióspecifikus viselkedésért tekintse meg az Azure.Identity API dokumentációját.

Fontos

Az Active Directory Alapértelmezett beállítással egyszerűsítheti a kapcsolati sztringek közötti különbségeket a különböző környezetek között. A teljesítmény azonban hatással lehet rá, mert több helyen is meg kell keresnie a hitelesítési információkat. Ha lassú kapcsolati sebességet lát az Active Directory alapértelmezett használatával, használjon egy másik hitelesítési lehetőséget, amely kifejezetten a környezetben használt hitelesítési módszert célozza meg. Az "Active Directory Alapértelmezett" nem ajánlott a szigorú szolgáltatási szintű válaszidőkkel rendelkező környezetekhez.

  • Környezeti hitelesítő
    • Engedélyezi a Microsoft Entra-azonosítóval való hitelesítést ügyfél- és titkos kód, felhasználónév és jelszó használatával, a következő környezeti változókban konfigurált részletekkel: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (További részletek)
  • WorkloadIdentityCredential
    • Engedélyezi a Microsoft Entra számítási feladatazonosító hitelesítését a Kubernetesen és más, a számítási feladatok identitását támogató gazdagépeken. További információ: Microsoft Entra Munkafolyamat azonosító. Az Azure Identity 1.10-es és a Microsoft.Data.SqlClient 5.1.4-es verziójától kezdve érhető el.
  • ManagedIdentityCredential
    • Megkísérli a hitelesítést a Microsoft Entra ID használatával az üzembe helyezési környezethez rendelt felügyelt identitással. A "Felhasználó által hozzárendelt kezelt identitás" "Ügyfél-azonosítója" a "Felhasználói azonosító" kapcsolati tulajdonságból olvasható be.
  • SharedTokenCacheCredential
    • A Microsoft-alkalmazások között megosztott helyi gyorsítótárban lévő tokenekkel hitelesít.
  • VisualStudioCredential
    • Hitelesítés engedélyezése a Microsoft Entra-azonosítóval a Visual Studióból származó adatok használatával
  • VisualStudioCodeCredential
    • Engedélyezi a Microsoft Entra-azonosítóval való hitelesítést a Visual Studio Code-ból származó adatok használatával.
  • AzurePowerShell-hitelesítő
    • Engedélyezheti a hitelesítést a Microsoft Entra ID segítségével az Azure PowerShell használatával. Az Azure Identity 1.6-os és a Microsoft.Data.SqlClient 5.0-s verziójától érhető el.
  • AzureCliCredential
    • Engedélyezi a Microsoft Entra ID hitelesítését az Azure CLI használatával a hozzáférési jogkivonat beszerzéséhez.
  • AzureDeveloperCliCredential
    • Lehetővé teszi a Microsoft Entra ID hitelesítését az Azure Developer CLI használatával a hozzáférési jogkivonat beszerzéséhez. Az Azure Identity 1.10-es és a Microsoft.Data.SqlClient 5.1.4-es verziójától kezdve érhető el.

Megjegyzés:

Az InteractiveBrowserCredential le van tiltva az Active Directory alapértelmezett illesztőprogram-implementációjában, és az Active Directory Interactive az egyetlen lehetőség, amely jogkivonatot szerezhet be MFA/Interaktív hitelesítés használatával.

További testreszabási lehetőségek jelenleg nem érhetők el.

Az alábbi példa bemutatja, hogyan használhatja az Active Directory alapértelmezett hitelesítését.

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

Munkaterhelési identitás hitelesítése

Az 5.2-es verziótól kezdődően elérhető a felügyelt identitásokhoz hasonlóan a számítási feladatok identitásának hitelesítési módja az ügyfél-azonosító kapcsolati sztringjében található User ID paraméter értékét használja, ha meg van adva. A felügyelt identitástól eltérően azonban a WorkloadIdentityCredentialOptions alapértelmezett értéke a környezeti változókból származik: AZURE_TENANT_ID, AZURE_CLIENT_ID és AZURE_FEDERATED_TOKEN_FILE. A kapcsolati sztring azonban csak az ügyfél-azonosítót bírálhatja felül.

Az alábbi példa egy felhasználó által hozzárendelt felügyelt identitással való hitelesítést mutatja be Active Directory Workload Identity a Microsoft.Data.SqlClient 5.2-es verziójától.

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

A Microsoft Entra hitelesítés testreszabása

Az illesztőprogramba épített Microsoft Entra-hitelesítés használata mellett a Microsoft.Data.SqlClient 2.1.0-s és újabb verziói lehetőséget biztosítanak az alkalmazások számára a Microsoft Entra hitelesítés testreszabására. A testreszabás az ActiveDirectoryAuthenticationProvider absztrakt osztályból származó SqlAuthenticationProvider osztályon alapul.

A Microsoft Entra-hitelesítés során az ügyfélalkalmazás a következő módokon határozhatja meg a saját ActiveDirectoryAuthenticationProvider osztályát:

  • Testreszabott visszahívási módszer használata.
  • Alkalmazás ügyfél-azonosítójának átadása az MSAL-kódtárnak SqlClient-illesztőn keresztül a hozzáférési jogkivonatok lekéréséhez.

Az alábbi példa bemutatja, hogyan használható egyéni visszahívás, amikor hitelesítést használ Active Directory Device Code Flow.

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

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

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

Testreszabott ActiveDirectoryAuthenticationProvider osztály esetén egy felhasználó által definiált alkalmazás ügyfél-azonosítója átadható az SqlClientnek, ha támogatott Microsoft Entra hitelesítési mód van használatban. A támogatott Microsoft Entra hitelesítési módok közé tartozik Active Directory Passworda , Active Directory Integrated, Active Directory Interactive, Active Directory Service Principalés Active Directory Device Code Flow.

Az alkalmazás ügyfél-azonosítója SqlAuthenticationProviderConfigurationSection vagy SqlClientAuthenticationProviderConfigurationSection használatával is konfigurálható. A konfigurációs tulajdonság applicationClientId a .NET-keretrendszer 4.6+ és a .NET Core 2.1+ verzióra vonatkozik.

Az alábbi kódrészlet példát mutat arra, hogyan lehet testreszabott ActiveDirectoryAuthenticationProvider osztályt használni egy felhasználó által definiált alkalmazásügyfél-azonosítóval, amikor a Active Directory Interactive hitelesítést használjuk.

using System;
using Microsoft.Data.SqlClient;

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

Az alábbi példa bemutatja, hogyan állíthat be egy alkalmazás ügyfél-azonosítóját egy konfigurációs szakaszon keresztül.

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

Az AccessTokenCallback használata

Az 5.2-es verziótól kezdve elérhető egy új AccessTokenCallback tulajdonság található az SqlConnectionen. A tulajdonsággal AccessTokenCallback definiálhat egy egyéni függvényt, amely hozzáférési jogkivonatot ad vissza a bejövő paraméterek alapján. A visszahívás használata jobb, mint az AccessToken tulajdonság használata, mert lehetővé teszi a hozzáférési jogkivonat frissítését egy kapcsolatkészleten belül. A AccessToken tulajdonság használatakor a jogkivonat nem frissíthető a kapcsolat megnyitása után. A tulajdonon keresztül nincs megadva lejárati dátum sem. Miután a token lejár, az új kapcsolatkísérletek szerver hitelesítési hibával sikertelenek lesznek, és az azt használó készleteket manuálisan kell törölni.

Fontos

Ugyanazon AccessTokenCallback bemeneti paraméterekhez azonos biztonsági környezet hozzáférési jogkivonatait kell visszaadnia. Ha a biztonsági környezet eltérő, előfordulhat, hogy a rendszer nem megfelelő biztonsági környezettel rendelkező készletezett kapcsolatot ad vissza a kapcsolati kérelemhez.

Megjegyzés:

AccessTokenCallback a kapcsolatkészletek azonosítására használt kulcs része. Ne hozzon létre új függvény-visszahívást az SqlConnection minden létrehozásához, mivel ez minden alkalommal új készletet eredményez. Hivatkozzon egy függvény ugyanarra a példányára a készletezéshez figyelembe venni kívánt kapcsolatokhoz. A kapcsolatkészlet kulcsa tartalmazza a visszahívásnak átadott paramétereket a kapcsolatkészletek megfelelő partícionálásához.

Az alábbi kódrészlet egy példa a AccessTokenCallback tulajdonság használatára a Microsoft.Data.SqlClient 5.2-es verziójától.

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

Egyéni SQL-hitelesítésszolgáltató támogatása

A nagyobb rugalmasság érdekében az ügyfélalkalmazás az osztály használata ActiveDirectoryAuthenticationProvider helyett saját szolgáltatóját is használhatja a Microsoft Entra hitelesítéshez. Az egyéni hitelesítésszolgáltatónak felülírt metódusokkal rendelkező SqlAuthenticationProvider alosztálynak kell lennie. Ezután regisztrálnia kell az egyéni szolgáltatót, felülbírálva egy vagy több meglévő Active Directory* hitelesítési módszert.

Fontos

A hitelesítésszolgáltatónak ugyanazon biztonsági környezethez tartozó hozzáférési jogkivonatokat kell visszaadnia ugyanazokhoz a bemeneti paraméterekhez. Ha a biztonsági környezet eltérő, előfordulhat, hogy a rendszer nem megfelelő biztonsági környezettel rendelkező készletezett kapcsolatot ad vissza a kapcsolati kérelemhez.

Az alábbi példa bemutatja, hogyan használhat új hitelesítésszolgáltatót a hitelesítéshez Active Directory Device Code Flow .

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

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

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

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

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

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

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

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

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

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

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

A hitelesítési élmény javítása Active Directory Interactive mellett a Microsoft.Data.SqlClient 2.1.0-s és újabb verziói a következő API-kat biztosítják az ügyfélalkalmazások számára az interaktív hitelesítés és az eszközkódfolyam-hitelesítés testreszabásához.

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

Lásd még