Aracılığıyla paylaş

Microsoft Entra kimlik doğrulaması ve SqlClient ile Azure SQL'e bağlanma

Şunlar için geçerlidir: .NET Framework .NET .NET Standard

ADO.NET'i indir

Bu makalede, SqlClient ile bir .NET uygulamasından Microsoft Entra kimlik doğrulamasını kullanarak Azure SQL veri kaynaklarına nasıl bağlanılacağı açıklanır.

Uyarı

Microsoft Entra ID, Azure Active Directory'nin (Azure AD) yeni adı olmasına rağmen, mevcut ortamların bozulmasını önlemek için Azure AD, UI alanları, bağlantı sağlayıcıları, hata kodları ve cmdletler gibi bazı sabit kodlu öğelerde hâlâ varlığını sürdürüyor. Bu makalede, iki ad birbirinin yerine kullanılabilir.

Genel Bakış

Microsoft Entra kimlik doğrulaması, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve Azure Synapse Analytics gibi veri kaynaklarına erişmek için Microsoft Entra Kimliği'ndeki kimlikleri kullanır. Microsoft.Data.SqlClient ad alanı, istemci uygulamalarının Azure SQL Veritabanı ve Azure SQL Yönetilen Örneği bağlanırken farklı kimlik doğrulama modlarında Microsoft Entra kimlik bilgilerini belirtmesine olanak tanır. Azure SQL ile Microsoft Entra kimlik doğrulamasını kullanmak için, Azure SQL ile Microsoft Entra kimlik doğrulamasını yapılandırmanız ve yönetmeniz gerekir.

Bağlantı dizesinde Authentication bağlantı özelliğini ayarladığınızda, istemci sağlanan değere göre tercih edilen bir Microsoft Entra kimlik doğrulama modunu seçebilir:

  • En eski Microsoft.Data.SqlClient sürümü .NET Framework, .NET Core ve .NET Standard'ı destekler Active Directory Password . Ayrıca Active Directory Integrated kimlik doğrulaması ve .NET Framework için Active Directory Interactive kimlik doğrulamasını destekler.

  • Microsoft.Data.SqlClient 2.0.0'dan başlayarak, kimlik doğrulaması ve Active Directory Integrated kimlik doğrulaması desteği Active Directory Interactive .NET Framework, .NET Core ve .NET Standard genelinde genişletilmiştir.

    SqlClient 2.0.0'da yeni Active Directory Service Principal bir kimlik doğrulama modu da eklenir. Kimlik doğrulamasını gerçekleştirmek için istemci kimliğini ve hizmet sorumlusu kimliğinin gizli dizisini kullanır.

  • Microsoft.Data.SqlClient 2.1.0'da, Active Directory Device Code Flow, ve Active Directory Managed Identity (ayrıca Active Directory MSI olarak da bilinir) dahil olmak üzere daha fazla kimlik doğrulama modu eklenir. Bu yeni modlar, uygulamanın sunucuya bağlanmak için bir erişim belirteci almasını sağlar.

Microsoft Entra kimlik doğrulaması hakkında aşağıdaki bölümlerde açıklananların ötesinde daha fazla bilgi için bkz: Microsoft Entra kimlik doğrulamasını kullanma.

Microsoft Entra kimlik doğrulamasını ayarlama

Uygulama, Microsoft Entra kimlik doğrulamasını kullanarak Azure SQL veri kaynaklarına bağlanırken geçerli bir kimlik doğrulama modu sağlaması gerekir. Aşağıdaki tabloda desteklenen kimlik doğrulama modları listelenmektedir. Uygulama, bağlantı dizesindeki Authentication connection özelliğini kullanarak bir mod belirtir.

Değer Açıklama Microsoft.Data.SqlClient sürümü
Active Directory Parolası Microsoft Entra kimliğinin kullanıcı adı ve parolasıyla kimlik doğrulama 1.0+
Active Directory Tümleşik Tümleşik Windows Kimlik Doğrulaması (IWA) kullanarak Microsoft Entra kimliğiyle kimlik doğrulama 2.0.0+1
Active Directory Etkileşimli Etkileşimli kimlik doğrulaması kullanarak Microsoft Entra kimliğiyle kimlik doğrulama 2.0.0+1
Active Directory Hizmet Sorumlusu İstemci kimliği ve gizli anahtarı kullanarak bir Microsoft Entra hizmet temsilcisi ile kimlik doğrulaması yapın. 2.0.0+
Active Directory Cihaz Kodu Süreci Cihaz Kodu Akışı modunu kullanarak Microsoft Entra kimliğiyle kimlik doğrulama 2.1.0+
Active Directory Yönetilen Kimlik,
Active Directory MSI		 Microsoft Entra sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimlik kullanarak kimlik doğrulama 2.1.0+
Active Directory Varsayılanı Yönetilen kimlikler, Visual Studio Code, Visual Studio, Azure CLI vb. dahil olmak üzere parolasız ve etkileşimli olmayan mekanizmaları kullanarak Microsoft Entra kimliğiyle kimlik doğrulaması yapın. 3.0.0+
Active Directory İş Yükü Kimliği İş Yükü Kimliği için etkinleştirilmiş Azure istemci ortamlarından SQL Veritabanı'na bağlanmak amacıyla federasyonlu Kullanıcı Tarafından Atanan Yönetilen Kimlik kullanarak Microsoft Entra kimliği ile kimlik doğrulaması yapın. 5.2.0+

1Microsoft.Data.SqlClient 2.0.0'dan Active Directory Integratedönce ve Active Directory Interactive kimlik doğrulama modları yalnızca .NET Framework'te desteklenir.

Parola kimlik doğrulamasını kullanma

Active Directory Password kimlik doğrulama modu, yerel veya federasyon Microsoft Entra kullanıcıları için Microsoft Entra Kimliği ile Azure veri kaynaklarına kimlik doğrulamasını destekler. Bu modu kullanırken, bağlantı dizesinde kullanıcı kimlik bilgilerinin sağlanması gerekir. Aşağıdaki örnekte kimlik doğrulamasının nasıl kullanılacağı Active Directory Password gösterilmektedir.

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

Tümleşik kimlik doğrulamayı kullanma

Kimlik doğrulama modunu kullanmak Active Directory Integrated için, bulutta Microsoft Entra ID'ye katılmış bir şirket içi Active Directory örneğiniz olmalıdır. Örneğin, Active Directory Federasyon Hizmetleri'ni (AD FS) kullanarak federasyon oluşturabilirsiniz.

Etki alanına katılmış bir makinede oturum açtığınızda, bu modda kimlik bilgileri istenmeden Azure SQL veri kaynaklarına erişebilirsiniz. .NET Framework uygulamaları için bağlantı dizesinde kullanıcı adı ve parola belirtemezsiniz. Kullanıcı adı, .NET Core ve .NET Standard uygulamaları için bağlantı dizesinde isteğe bağlıdır. Bu modda SqlConnection özelliğini ayarlayamazsınız Credential .

Aşağıdaki kod parçacığı, kimlik doğrulamasının ne zaman Active Directory Integrated kullanımda olduğuna dair bir örnektir.

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

Etkileşimli kimlik doğrulamasını kullanma

Active Directory Interactive kimlik doğrulaması, Azure SQL veri kaynaklarına bağlanmak için çok faktörlü kimlik doğrulama teknolojisini destekler. Bağlantı dizesinde bu kimlik doğrulama modunu sağlarsanız, bir Azure kimlik doğrulama ekranı görüntülenir ve kullanıcıdan geçerli kimlik bilgileri girmesini ister. Bağlantı dizesinde parolayı belirtemezsiniz.

Bu modda SqlConnection özelliğini ayarlayamazsınız Credential . Microsoft.Data.SqlClient 2.0.0 ve sonraki sürümlerde, etkileşimli moddayken bağlantı dizesinde kullanıcı adına izin verilir.

Aşağıdaki örnekte kimlik doğrulamasının nasıl kullanılacağı Active Directory Interactive gösterilmektedir.

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

Hizmet sorumlusu kimlik doğrulamasını kullanma

Active Directory Service Principal Kimlik doğrulama modunda, istemci uygulaması bir hizmet sorumlusunun istemci kimliğini ve gizli anahtarını sağlayarak Azure SQL veri kaynaklarına bağlanabilir. Hizmet sorumlusu kimlik doğrulaması şunları içerir:

  1. Gizli anahtar ile bir uygulama kaydı ayarlama.
  2. Azure SQL Veritabanı örneğinde uygulamaya izin verme.
  3. Doğru kimlik bilgileriyle bağlanma.

Aşağıdaki örnekte kimlik doğrulamasının nasıl kullanılacağı Active Directory Service Principal gösterilmektedir.

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

Cihaz kodu akışı ile kimlik doğrulamasını kullanma

.NET için Microsoft Kimlik Doğrulama Kitaplığı (MSAL.NET) ile kimlik doğrulaması, Active Directory Device Code Flow istemci uygulamasının etkileşimli bir web tarayıcısı olmayan cihazlardan ve işletim sistemlerinden Azure SQL veri kaynaklarına bağlanmasını sağlar. Etkileşimli kimlik doğrulama başka bir cihazda gerçekleştirilir. Cihaz kodu akışı kimlik doğrulaması hakkında daha fazla bilgi için OAuth 2.0 Cihaz Kodu Akışı başlıklı makaleye bakın.

Bu mod kullanımdayken, Credential özelliğini SqlConnection ayarlayamazsınız. Ayrıca, kullanıcı adı ve parola bağlantı dizesinde belirtilmemelidir.

Aşağıdaki kod parçacığı, kimlik doğrulamasının kullanılmasına Active Directory Device Code Flow bir örnektir.

Uyarı

için Active Directory Device Code Flow zaman aşımı varsayılan olarak bağlantı Connect Timeout ayarına ayarlanır. Cihaz kodu akışı kimlik doğrulama işleminden geçmek için yeterli süre sağlayan bir Connect Timeout belirttiğinizden emin olun.

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

Yönetilen kimlik doğrulamasını kullanma

Azure kaynakları için Yönetilen Kimliklerle kimlik doğrulaması, SQL'e programlı erişim için önerilen kimlik doğrulama yöntemidir. İstemci uygulaması, bir kaynağın sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliğini kullanarak Microsoft Entra ID ile SQL'de kimlik doğrulaması yapabilir. Bu kimlik sağlanarak, erişim belirteçleri almak için kullanılır. Bu yöntem, kimlik bilgilerini ve gizli dizileri yönetme gereksinimini ortadan kaldırır ve erişim yönetimini basitleştirebilir.

Yönetilen kimliklerin iki türü vardır:

  • Sistem tarafından atanan yönetilen kimlik , bir Azure kaynağının (SQL yönetilen örneği veya mantıksal sunucu gibi) bir parçası olarak oluşturulur ve bu kaynağın yaşam döngüsünü paylaşır. Sistem tarafından atanan kimlikler yalnızca tek bir Azure kaynağıyla ilişkilendirilebilir.
  • Kullanıcı tarafından atanan yönetilen kimlik , tek başına bir Azure kaynağı olarak oluşturulur. Bir Azure hizmetinin bir veya daha fazla örneğine atanabilir.

Yönetilen kimlikler hakkında daha fazla bilgi için Azure kaynakları için yönetilen kimlikler hakkında bölümüne bakın.

Microsoft.Data.SqlClient 2.1.0'dan bu yana sürücü, yönetilen kimlik aracılığıyla erişim belirteçleri alarak Azure SQL Veritabanı, Azure Synapse Analytics ve Azure SQL Yönetilen Örneği kimlik doğrulamasını destekler. Bu kimlik doğrulamasını kullanmak için bağlantı dizesinde ya Active Directory Managed Identity ya da Active Directory MSI belirtin, ve parola gerekmez. Bu modda Credential özelliğini SqlConnection da ayarlayamazsınız.

Kullanıcı tarafından atanan yönetilen kimlik için, Microsoft.Data.SqlClient v3.0 veya daha yeni bir sürüm kullanılırken yönetilen kimliğin istemci kimliği sağlanmalıdır. Microsoft.Data.SqlClient v2.1 kullanılıyorsa, yönetilen kimliğin nesne kimliği sağlanmalıdır.

Sistem tarafından atanan yönetilen kimlikle kimlik doğrulamanın nasıl kullanılacağını, aşağıdaki örnekte Active Directory Managed Identity gösterilmektedir.

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

Aşağıdaki örnekte, Active Directory Managed Identity ile kullanıcı tarafından atanan yönetilen kimlikle kimlik doğrulaması gösterilmektedir.

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

Aşağıdaki örnekte, Active Directory Managed Identity ile kullanıcı tarafından atanan yönetilen kimlikle kimlik doğrulaması gösterilmektedir.

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

Varsayılan kimlik doğrulamasını kullanma

Sürüm 3.0'dan itibaren kullanılabilen bu kimlik doğrulama modu, kullanıcı kimlik doğrulama olanaklarını genişletir. Bu mod, oturum açma çözümlerini istemci ortamına, Visual Studio Code'a, Visual Studio'ya, Azure CLI'ye vb. genişletir.

Bu kimlik doğrulama modunda, sürücü Azure Kimlik kitaplığından "DefaultAzureCredential" öğesini geçirerek bir erişim belirteci alır. Bu mod, sırasıyla bir erişim tokenı edinmek için çeşitli kimlik bilgisi türlerini kullanmaya çalışır. Kullanılan Azure Kimlik kitaplığının sürümüne bağlı olarak, kimlik bilgileri kümesi değişir. Sürüme özgü farklılıklar listede belirtilmiştir. Azure Identity sürümüne özgü davranış için Azure.Identity API belgelerine bakın.

Önemli

Active Directory Varsayılan , farklı ortamlar arasındaki bağlantı dizesi farklarını basitleştirmek için kullanışlı bir seçenektir. Ancak, kimlik doğrulama bilgileri için birden çok yere bakabilmesi gerektiğinden performans etkileri de olabilir. Active Directory Varsayılanı'nı kullanarak düşük bağlantı hızları görürseniz, ortamınızda kullandığınız kimlik doğrulama yöntemini özellikle hedefleyen farklı bir kimlik doğrulama seçeneği kullanın. Katı hizmet düzeyi yanıt sürelerine sahip ortamlar için "Active Directory Varsayılanı" önerilmez.

  • EnvironmentCredential
    • İstemci ve gizli dizi veya kullanıcı adı ve parola kullanarak Microsoft Entra Id ile kimlik doğrulamasını etkinleştirir. Aşağıdaki ortam değişkenlerinde yapılandırılan ayrıntılar: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Diğer ayrıntılar)
  • WorkloadIdentityCredential
    • Kubernetes'te ve iş yükü kimliğini destekleyen diğer ana bilgisayarlarda Microsoft Entra İş Yükü Kimliği kimlik doğrulamasını etkinleştirir. Daha fazla bilgi için bkz. Microsoft Entra İş Yükü Kimliği. Azure Identity sürüm 1.10 ve Microsoft.Data.SqlClient 5.1.4'ten itibaren kullanılabilir.
  • ManagedIdentityCredential
    • Dağıtım ortamına atanmış bir yönetilen kimlik kullanarak Microsoft Entra ID ile kimlik doğrulamasını dener. "Kullanıcı Tarafından Atanan Yönetilen Kimlik"in "İstemci Kimliği" , "Kullanıcı Kimliği" bağlantı özelliğinden okunur.
  • SharedTokenCacheCredential
    • Microsoft uygulamaları arasında paylaşılan yerel önbellekteki belirteçleri kullanarak kimlik doğrulaması yapar.
  • VisualStudioCredential
    • Visual Studio'dan alınan verileri kullanarak Microsoft Entra Id ile kimlik doğrulamasını etkinleştirir
  • VisualStudioCodeCredential
    • Visual Studio Code'dan alınan verileri kullanarak Microsoft Entra Id ile kimlik doğrulamasını etkinleştirir.
  • AzurePowerShellCredential
    • Azure PowerShell kullanarak Microsoft Entra ID ile kimlik doğrulamasını etkinleştirir. Azure Identity sürüm 1.6 ve Microsoft.Data.SqlClient 5.0'dan itibaren kullanılabilir.
  • AzureCliCredential
    • Erişim belirteci almak için Azure CLI kullanarak Microsoft Entra Kimliği ile kimlik doğrulamasını etkinleştirir.
  • AzureDeveloperCliCredential
    • Azure Geliştirici CLI'sini kullanarak Microsoft Entra ID kimlik doğrulamasını erişim belirteci almak için etkinleştirir. Azure Identity sürüm 1.10 ve Microsoft.Data.SqlClient 5.1.4'ten itibaren kullanılabilir.

Uyarı

InteractiveBrowserCredential, Active Directory Varsayılanı'nın sürücü uygulamasında devre dışı bırakılmıştır ve MFA/Etkileşimli kimlik doğrulamasıyla belirteç almak için kullanılabilen tek seçenek Active Directory Interactive'dir.

Şu anda başka özelleştirme seçenekleri sağlanmamaktadır.

Aşağıdaki örnekte Active Directory Varsayılan kimlik doğrulamasının nasıl kullanılacağı gösterilmektedir.

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

İş yükü kimlik doğrulamasını kullanma

Yönetilen kimliklerde olduğu gibi sürüm 5.2'den itibaren kullanılabilen iş yükü kimlik doğrulama modu, belirtilmişse İstemci Kimliği için bağlantı dizesindeki parametrenin User ID değerini kullanır. Ancak yönetilen kimlikten farklı olarak WorkloadIdentityCredentialOptions, değerini ortam değişkenlerinden varsayılan olarak alır: AZURE_TENANT_ID, AZURE_CLIENT_ID ve AZURE_FEDERATED_TOKEN_FILE. Ancak, bağlantı dizesi tarafından yalnızca İstemci Kimliği geçersiz kılınabilir.

Aşağıdaki örnekte, Active Directory Workload Identity ile kullanıcı tarafından atanan yönetilen kimlikle kimlik doğrulaması gösterilmektedir.

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

Microsoft Entra kimlik doğrulamasını özelleştirme

Microsoft.Data.SqlClient 2.1.0 ve sonraki sürümler, sürücüde yerleşik olarak bulunan Microsoft Entra kimlik doğrulamasını kullanmanın yanı sıra, uygulamalara Microsoft Entra kimlik doğrulamasını özelleştirme seçeneği sunar. Özelleştirme, ActiveDirectoryAuthenticationProvider soyut sınıfından türetilmiş olan SqlAuthenticationProvider sınıfına dayanır.

Microsoft Entra kimlik doğrulaması sırasında, istemci uygulama kendi sınıfını aşağıdakilerden birini kullanarak tanımlayabilir ActiveDirectoryAuthenticationProvider :

  • Özelleştirilmiş bir geri çağrım yöntemi kullanma.
  • Erişim belirteçlerini getirmek için SqlClient sürücüsü aracılığıyla MSAL kitaplığına bir uygulama istemci kimliği geçirme.

Kimlik doğrulama kullanımdayken Active Directory Device Code Flow özel bir geri aramanın nasıl kullanılacağını gösteren aşağıdaki örnek.

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

Özelleştirilmiş ActiveDirectoryAuthenticationProvider bir sınıfla, desteklenen bir Microsoft Entra kimlik doğrulama modu kullanımda olduğunda kullanıcı tanımlı bir uygulama istemci kimliği SqlClient'a geçirilebilir. Desteklenen Microsoft Entra kimlik doğrulama modları arasında Active Directory Password, Active Directory Integrated, Active Directory InteractiveActive Directory Service Principal, ve Active Directory Device Code Flowbulunur.

Uygulama istemci kimliği, SqlAuthenticationProviderConfigurationSection veya SqlClientAuthenticationProviderConfigurationSection aracılığıyla da yapılandırılabilir. Yapılandırma özelliği applicationClientId .NET Framework 4.6+ ve .NET Core 2.1+ için geçerlidir.

ActiveDirectoryAuthenticationProvider kimlik doğrulaması kullanımda olduğunda kullanıcı tanımlı uygulama istemci kimliğiyle özelleştirilmiş Active Directory Interactive bir sınıf kullanma örneği aşağıdaki kod parçacığında yer almaktadır.

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

Aşağıdaki örnekte, bir yapılandırma bölümü aracılığıyla bir uygulama istemci kimliğinin nasıl ayarlanacağı gösterilmektedir.

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

AccessTokenCallback'i kullanma

Sürüm 5.2'den itibaren kullanılabilen SqlConnection'da yeni bir AccessTokenCallback özelliği vardır. AccessTokenCallback Gelen parametreler göz önüne alındığında bir erişim belirteci döndüren özel bir işlev tanımlamak için özelliğini kullanın. Geri çağırmayı kullanmak, erişim belirtecinin bir bağlantı havuzu içinde yenilenmesine izin verdiği için AccessToken özelliğini kullanmaktan daha iyidir. Özellik kullanılırken AccessToken , bağlantı açıldıktan sonra belirteç güncelleştirilemez. Ayrıca, mülk aracılığıyla sağlanan ilişkili bir son kullanma tarihi de yoktur. Belirtecin süresi dolduktan sonra, yeni bağlantı istekleri bir sunucu kimlik doğrulama hatasıyla başarısız olur ve belirteci kullanan havuzların el ile temizlenmesi gerekir.

Önemli

Girilen aynı giriş parametreleri için, AccessTokenCallback aynı güvenlik bağlamına sahip erişim belirteçlerini döndürmelidir. Güvenlik bağlamı farklıysa, bağlantı isteği için yanlış güvenlik bağlamına sahip havuzlanmış bir bağlantı geri döndürülebilir.

Uyarı

AccessTokenCallback bağlantı havuzlarını tanımlamak için kullanılan anahtarın bir parçasıdır. Her seferinde yeni bir havuzla sonuçlanan her SqlConnection oluşturma işlemi için yeni bir işlev geri çağrısı oluşturmaktan kaçının. Havuzlamaya dahil edilmesini istediğiniz bağlantılar için bir fonksiyonun aynı örneğine başvurduğunuzdan emin olun. Bağlantı havuzu anahtarı, bağlantı havuzlarını uygun şekilde bölümlemek için geri çağırmaya geçirilen parametreleri içerir.

Aşağıdaki kod parçacığı, AccessTokenCallback sürümlerde özelliğin kullanımına bir örnektir.

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

Özel bir SQL kimlik doğrulama sağlayıcısı desteği

İstemci uygulamasına daha fazla esneklik sağlandığında, Microsoft Entra kimlik doğrulaması için ActiveDirectoryAuthenticationProvider sınıfını kullanmak yerine kendi sağlayıcısını da kullanabilir. Özel kimlik doğrulama sağlayıcısı, yöntemleri geçersiz kılınmış SqlAuthenticationProvider sınıfının bir alt sınıfı olmalıdır. Daha sonra, mevcut Active Directory* kimlik doğrulama yöntemlerinden birini veya daha fazlasını geçersiz kılarak özel sağlayıcıyı kaydetmesi gerekir.

Önemli

Bir kimlik doğrulama sağlayıcısı, aynı giriş parametreleri için aynı güvenlik bağlamının erişim belirteçlerini döndürmelidir. Güvenlik bağlamı farklıysa, bağlantı isteği için yanlış güvenlik bağlamına sahip havuzlanmış bir bağlantı geri döndürülebilir.

Aşağıdaki örnekte, kimlik doğrulaması için Active Directory Device Code Flow yeni bir kimlik doğrulama sağlayıcısının nasıl kullanılacağı gösterilmektedir.

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

Kimlik doğrulama deneyimini geliştirmenin Active Directory Interactive yanı sıra, Microsoft.Data.SqlClient 2.1.0 ve üzeri, etkileşimli kimlik doğrulamasını ve cihaz kodu akışı kimlik doğrulamasını özelleştirmek için istemci uygulamaları için aşağıdaki API'leri sağlar.

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

Ayrıca bakınız