Использование проверки подлинности Azure Active Directory для SqlClient

Область применения: .NET Framework .NET Core .NET Standard

Скачать ADO.NET

В этой статье показано, как подключаться к источникам данных Azure SQL с помощью проверки подлинности Azure Active Directory (AAD) из приложения .NET с помощью SqlClient.

Проверка подлинности AAD использует удостоверения AAD для доступа к источникам данных Azure SQL, таким как База данных SQL Azure, Управляемый экземпляр Azure SQL и Azure Synapse Analytics. Пространство имен Microsoft.Data.SqlClient позволяет клиентским приложениям указывать учетные данные AAD в разных режимах проверки подлинности при подключении к Базе данных SQL Azure. Для использования проверки подлинности Azure AD необходимо настроить источник данных Azure SQL. Дополнительные сведения см. в статье о настройке проверки подлинности Azure AD и управлении ею с помощью Azure SQL.

Указывая свойство подключения Authentication в строке подключения, клиент может выбрать предпочтительный режим проверки подлинности AAD с учетом указанного значения:

  • Самая ранняя версия Microsoft.Data.SqlClient поддерживает Active Directory Password для .NET Framework, .NET Core и .NET Standard. Также она поддерживает проверку подлинности Active Directory Integrated и Active Directory Interactive для .NET Framework.

  • Начиная с версии Microsoft.Data.SqlClient 2.0.0, проверка подлинности Active Directory Integrated и Active Directory Interactive также поддерживается для .NET Framework, .NET Core и .NET Standard.

    Также в SqlClient 2.0.0 добавлен новый режим проверки подлинности Active Directory Service Principal. Для выполнения проверки подлинности используется идентификатор клиента и секрет удостоверения субъекта-службы.

  • Дополнительные режимы проверки подлинности добавлены в Microsoft.Data.SqlClient версии 2.1.0, в том числе Active Directory Device Code Flow и Active Directory Managed Identity (или Active Directory MSI). Эти новые режимы позволяют приложению получить маркер доступа для подключения к серверу.

Если вам недостаточно сведений о проверке подлинности Azure AD, которые представлены в следующих разделах, см. статью Использование проверки подлинности Azure Active Directory.

Настройка проверки подлинности Azure Active Directory

Когда приложение подключается к источникам данных SQL Azure с использованием проверки подлинности Azure AD, должен использоваться допустимый режим проверки подлинности. В следующей таблице перечислены поддерживаемые режимы проверки подлинности. Приложение может задать режим через свойство подключения Authentication в строке подключения.

Значение Описание Версия Microsoft.Data.SqlClient
Пароль Active Directory Проверка подлинности по удостоверению Azure AD с использованием имени пользователя и пароля. 1.0+
Встроенная проверка подлинности Active Directory Проверка подлинности по удостоверению Azure AD с использованием встроенной проверки подлинности. 2.0.0 и выше1
Интерактивная проверка подлинности Active Directory Интерактивная проверка подлинности с использованием удостоверения Azure AD. 2.0.0 и выше1
Субъект-служба Active Directory Проверка подлинности по удостоверению Azure AD с использованием идентификатора клиента и секрета удостоверения субъекта-службы. 2.0.0 и выше
Потока кода устройства Active Directory Проверка подлинности по удостоверению Azure AD в режиме потока кода устройства. 2.1.0 и выше
Управляемое удостоверение Active Directory,
Active Directory MSI
Проверка подлинности по удостоверению Azure AD с использованием управляемого удостоверения, назначаемого системой или пользователем. 2.1.0 и выше
Active Directory по умолчанию Проверяйте подлинность с помощью удостоверения Azure AD, используя беспарольные и неинтерактивные механизмы, включая управляемые удостоверения, Visual Studio Code, Visual Studio, Azure CLI и т. д. 3.0.0+

1 В версиях Microsoft.Data.SqlClient ниже 2.0.0 режимы проверки подлинности Active Directory Integrated и Active Directory Interactive поддерживаются только для .NET Framework.

Использование проверки подлинности по паролю Active Directory

Режим проверки подлинности Active Directory Password поддерживает проверку подлинности в источниках данных Azure с использованием Azure AD для собственных и федеративных пользователей Azure AD. При использовании этого режима в строке подключения необходимо указать учетные данные пользователя. Следующий пример демонстрирует применение проверки подлинности Active Directory Password.

// 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=***";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Использование интегрированной проверки подлинности Active Directory

Чтобы использовать режим проверки подлинности Active Directory Integrated, нужно настроить федерацию локального экземпляра Active Directory с Azure AD в облаке. Например, федерацию можно выполнять с помощью службы федерации Active Directory (AD FS).

В этом режиме после входа на присоединенный к домену компьютер вы сможете получать доступ к источникам данных Azure SQL, не вводя учетные данные. Имя пользователя и пароль нельзя указывать в строке подключения для приложений .NET Framework. Имя пользователя является необязательным параметром в строке подключения для приложений .NET Core и .NET Standard. В этом режиме нельзя задать свойство Credential для SqlConnection.

Следующий фрагмент кода демонстрирует пример использования проверки подлинности Active Directory Integrated.

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

Использование интерактивной проверки подлинности Active Directory

Проверка подлинности Active Directory Interactive поддерживает технологию многофакторной проверки подлинности для подключения к источникам данных Azure SQL. Если в строке подключения указан этот режим проверки подлинности, отобразится экран проверки подлинности Azure, где пользователю будет предложено ввести допустимые учетные данные. Вы не сможете указать пароль в строке подключения.

В этом режиме нельзя задать свойство Credential для SqlConnection. При использовании Microsoft.Data.SqlClient версии 2.0.0 и выше в интерактивном режиме можно указывать имя пользователя в строке подключения.

Следующий пример демонстрирует применение проверки подлинности Active Directory Interactive.

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

Использование проверки подлинности субъекта-службы Active Directory

В режиме проверки подлинности Active Directory Service Principal клиентское приложение может подключаться к источникам данных SQL Azure, предоставляя идентификатор клиента и секрет удостоверения субъекта-службы. Проверка подлинности на основе субъекта-службы включает следующие действия:

  1. настройка регистрации приложения с секретом;
  2. предоставление приложению разрешений в экземпляре базы данных Azure SQL;
  3. подключение с правильными учетными данными.

Следующий пример демонстрирует применение проверки подлинности Active Directory Service Principal.

// 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=secret";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Использование проверки подлинности в потоке кода устройства Active Directory

При использовании библиотеки проверки подлинности Майкрософт для .NET (MSAL.NET) клиентское приложение сможет использовать проверку подлинности Active Directory Device Code Flow для подключения к источникам данных SQL Azure с устройств и операционных систем, в которых нет интерактивного веб-браузера. Интерактивная проверка подлинности выполняется на другом устройстве. Дополнительные сведения см. в статье Платформа удостоверений Майкрософт и поток предоставления авторизации устройства OAuth 2.0.

Если используется этот режим, нельзя задать свойство Credential для SqlConnection. Кроме того, нельзя указать имя пользователя и пароль в строке подключения.

Следующий фрагмент кода демонстрирует пример с проверкой подлинности Active Directory Device Code Flow.

// Use your own server and database.
string ConnectionString = @"Server=demo.database.windows.net; Authentication=Active Directory Device Code Flow; Encrypt=True; Database=testdb";

using (SqlConnection conn = new SqlConnection(ConnectionString)) {
    conn.Open();
}

Использование проверки подлинности Active Directory с управляемым удостоверением

Управляемые удостоверения для ресурсов Azure — это новое название службы "Управляемое удостоверение службы" (MSI). Когда клиентское приложение использует ресурс Azure для обращения к службе Azure, которая поддерживает проверку подлинности Azure AD, вы можете использовать для проверки подлинности управляемые удостоверения, предоставив удостоверение для ресурса Azure в Azure AD. Предоставленное удостоверение можно использовать для получения маркеров доступа. При таком способе проверки подлинности управлять учетными данными и секретами не нужно.

Существует два типа управляемых удостоверений.

  • Назначаемое системой управляемое удостоверение создается в экземпляре службы в Azure AD. Оно привязано к жизненному циклу этого экземпляра службы.
  • Назначаемое пользователем управляемое удостоверение создается как изолированный ресурс Azure. Его можно назначить одному или нескольким экземплярам службы Azure.

Дополнительные сведения об управляемых удостоверениях см. в статье Что такое управляемые удостоверения для ресурсов Azure?

Начиная с версии Microsoft.Data.SqlClient 2.1.0, драйвер поддерживает проверку подлинности в Базе данных SQL Azure, Azure Synapse Analytics и Управляемом экземпляре Azure SQL путем получения маркеров доступа по управляемому удостоверению. Чтобы использовать такую проверку подлинности, укажите Active Directory Managed Identity или Active Directory MSI в строке подключения. Пароль при этом не требуется. В этом режиме также нельзя задать свойство Credential для SqlConnection.

Для назначаемого пользователем управляемого удостоверения необходимо указать идентификатор клиента для управляемого удостоверения, если вы используете Microsoft.Data.SqlClient версии 3.0 или более поздней. При использовании Microsoft.Data.SqlClient версии 2.1 необходимо предоставить идентификатор объекта управляемого удостоверения.

Следующий пример демонстрирует, как использовать проверку подлинности Active Directory Managed Identity с управляемым удостоверением, назначаемым системой.

// For system-assigned managed identity
// Use your own 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();
}

В следующем примере демонстрируется проверка подлинности Active Directory Managed Identity с управляемым удостоверением, назначаемым пользователем, с помощью Microsoft.Data.SqlClient версии 3.0 или более поздней.

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

В следующем примере демонстрируется проверка подлинности Active Directory Managed Identity с управляемым удостоверением, назначаемым пользователем, с помощью Microsoft.Data.SqlClient версии 2.1.

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

Использование проверки подлинности Active Directory по умолчанию

Этот режим проверки подлинности расширяет возможности проверки подлинности пользователей, дополняя решения для входа в клиентскую среду, Visual Studio Code, Visual Studio Azure CLI и т. д.

В этом режиме проверки подлинности драйвер получает маркер, передавая DefaultAzureCredential из библиотеки удостоверений Azure для получения маркера доступа. Этот режим пытается использовать эти типы учетных данных для получения маркера доступа в следующем порядке:

  • EnvironmentCredential
    • Включает проверку подлинности для Azure Active Directory с помощью клиента и секрета, или имени пользователя и пароля, сведений, настроенных в следующих переменных среды: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (дополнительные сведения)
  • ManagedIdentityCredential
    • Пытается выполнить проверку подлинности для Azure Active Directory с помощью управляемого удостоверения, назначенного среде развертывания. "Client Id" для управляемого удостоверения, назначенного пользователю, считывается из свойства подключения "User Id" .
  • SharedTokenCacheCredential
    • Проверяет подлинность с использованием токенов в локальном кэше, совместно используемом приложениями Майкрософт.
  • VisualStudioCredential
    • Включает проверку подлинности для Azure Active Directory с использованием данных из Visual Studio.
  • VisualStudioCodeCredential
    • Включает проверку подлинности для Azure Active Directory с использованием данных из Visual Studio Code.
  • AzureCliCredential
    • Включает проверку подлинности для Azure Active Directory, используя Azure CLI для получения маркера доступа.

Примечание

InteractiveBrowserCredential отключен в реализации драйвера "Active Directory по умолчанию", и "интерактивная проверка подлинности Active Directory" — это единственный вариант, доступный для получения маркера с использованием многофакторной или интерактивной проверки подлинности.

Дополнительные варианты настройки в данный момент недоступны.

В следующем примере показано, как использовать проверку подлинности Active Directory по умолчанию.

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

Настройка проверки подлинности Active Directory

Помимо возможности использования встроенной в драйвер проверки подлинности Active Directory, Microsoft.Data.SqlClient версии 2.1.0 и выше позволяет приложениям настраивать проверку подлинности Active Directory. Эта настройка основывается на классе ActiveDirectoryAuthenticationProvider, который является производным от абстрактного класса SqlAuthenticationProvider.

В процессе проверки подлинности Active Directory клиентское приложение может определить собственный класс ActiveDirectoryAuthenticationProvider одним из следующих способов:

  • через пользовательский метод обратного вызова;
  • передавая идентификатора клиента приложения в библиотеку MSAL через драйвер SqlClient для получения маркеров доступа.

Следующий пример демонстрирует, как использовать пользовательский обратный вызов при работе с проверкой подлинности 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);
        }
    }
}

Используя настраиваемый класс ActiveDirectoryAuthenticationProvider, можно передать определяемый пользователем идентификатор клиента в SqlClient при работе с любым поддерживаемым режимом проверки подлинности Active Directory. Поддерживаются следующие режимы проверки подлинности Active Directory: Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principal и Active Directory Device Code Flow.

Также идентификатор клиента приложения можно настроить с помощью SqlAuthenticationProviderConfigurationSection или SqlClientAuthenticationProviderConfigurationSection. Свойство конфигурации applicationClientId применяется к .NET Framework 4.6 и выше и .NET Core 2.1 и выше.

Следующий фрагмент кода демонстрирует пример использования настраиваемого класса ActiveDirectoryAuthenticationProvider с определяемым пользователем идентификатором клиента приложения при работе с проверкой подлинности Active Directory Interactive.

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

Следующий пример демонстрирует, как задать идентификатор клиента приложения в разделе конфигурации.

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

Поддержка пользовательского поставщика проверки подлинности SQL

Благодаря гибким возможностям клиентское приложение может использовать собственный поставщик проверки подлинности Active Directory вместо стандартного класса ActiveDirectoryAuthenticationProvider. Пользовательский поставщик проверки подлинности нужно реализовать в виде подкласса SqlAuthenticationProvider с переопределенными методами. Затем необходимо зарегистрировать настраиваемый поставщик, переопределив один или несколько существующих методов проверки подлинности Active Directory*.

Следующий пример демонстрирует, как использовать новый поставщик проверки подлинности для проверки подлинности Active Directory Device Code Flow.

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

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
    {
        public override async Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters)
        {
            string clientId = "my-client-id";
            string clientName = "My Application Name";
            string s_defaultScopeSuffix = "/.default";

            string[] scopes = new string[] { parameters.Resource.EndsWith(s_defaultScopeSuffix) ? parameters.Resource : parameters.Resource + s_defaultScopeSuffix };

            IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
                .WithAuthority(parameters.Authority)
                .WithClientName(clientName)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .Build();

            AuthenticationResult result = await app.AcquireTokenWithDeviceCode(scopes,
                    deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult)).ExecuteAsync();
            return new SqlAuthenticationToken(result.AccessToken, result.ExpiresOn);
        }

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

        private Task CustomDeviceFlowCallback(DeviceCodeResult result)
        {
            Console.WriteLine(result.Message);
            return Task.FromResult(0);
        }
    }

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

Наряду с улучшением интерфейса для проверки подлинности Active Directory Interactive в Microsoft.Data.SqlClient версии 2.1.0 и выше клиентским приложениям предоставляются следующие API для настройки интерактивной проверки подлинности и проверки подлинности в потоке кода устройства.

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 Xamarin.iOS), Activity (if using Xamarin.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 will let 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();
}

См. также