Compartir a través de

Conexión a Azure SQL con la autenticación de Microsoft Entra y SqlClient

Se aplica a: .NET Framework .NET .NET Standard

Descargar ADO.NET

En este artículo se describe cómo conectarse a orígenes de datos de Azure SQL mediante la autenticación de Microsoft Entra desde una aplicación .NET con SqlClient.

Nota:

Aunque Microsoft Entra ID es el nuevo nombre de Azure Active Directory (Azure AD), para evitar interrumpir los entornos existentes, Azure AD sigue estando en algunos elementos codificados de forma rígida como campos de interfaz de usuario, proveedores de conexiones, códigos de error y cmdlets. En este artículo, los dos nombres son intercambiables.

Información general

La autenticación de Microsoft Entra usa identidades en Microsoft Entra ID para tener acceso a orígenes de datos como la base de datos de Azure SQL, Azure SQL Managed Instance y Azure Synapse Analytics. El espacio de nombres Microsoft.Data.SqlClient permite a las aplicaciones cliente especificar credenciales de Microsoft Entra en modos de autenticación diferentes cuando se conectan a la base de datos de Azure SQL y Azure SQL Managed Instance. Para usar la autenticación de Microsoft Entra con Azure SQL, debes configurar y administrar la autenticación de Microsoft Entra con Azure SQL.

Al establecer la propiedad de conexión Authentication en la cadena de conexión, el cliente puede elegir un modo de autenticación de Microsoft Entra preferido según el valor proporcionado:

  • La versión más antigua de Microsoft.Data.SqlClient admite Active Directory Password para .NET Framework, .NET Core y .NET Standard. También admite la autenticación Active Directory Integrated y la autenticación Active Directory Interactive para .NET Framework.

  • A partir de Microsoft.Data.SqlClient 2.0.0, se amplió la compatibilidad con la autenticación Active Directory Integrated y la autenticación Active Directory Interactive en .NET Framework, .NET Core y .NET Standard.

    También se agregó un nuevo modo de autenticación Active Directory Service Principal en SqlClient 2.0.0. Hace uso del identificador y el secreto de cliente de una identidad de entidad de servicio para realizar la autenticación.

  • Se han agregado más modos de autenticación en Microsoft. Data. SqlClient 2.1.0, incluidos Active Directory Device Code Flow y Active Directory Managed Identity (también conocido como Active Directory MSI). Estos nuevos modos permiten a la aplicación adquirir un token de acceso para conectarse al servidor.

Para obtener información sobre la autenticación de Microsoft Entra más allá de lo que describen las secciones siguientes, consulta Uso de la autenticación de Microsoft Entra.

Configuración de la autenticación de Microsoft Entra

Cuando la aplicación se conecta a orígenes de datos de Azure SQL mediante la autenticación de Microsoft Entra, debe proporcionar un modo de autenticación válido. En la tabla siguiente se enumeran los modos de autenticación admitidos. La aplicación especifica un modo mediante el uso de la propiedad de conexión Authentication en la cadena de conexión.

Valor Descripción Versión de Microsoft.Data.SqlClient
Contraseña de Active Directory Autenticar con el nombre de usuario y la contraseña de una identidad de Microsoft Entra 1.0+
Integrado en Active Directory Autentícate con una identidad de Microsoft Entra mediante la Autenticación integrada de Windows (IWA) 2.0.0+1
Active Directory interactivo Autentícate con una identidad de Microsoft Entra mediante la autenticación interactiva 2.0.0+1
Principal de servicio de Active Directory Autenticación con una entidad de servicio de Microsoft Entra, utilizando su id. de cliente y secreto 2.0.0+
Flujo de código de dispositivo de Active Directory Autentíquese con una identidad de Microsoft Entra mediante el modo de flujo de código de dispositivo 2.1.0+
Identidad administrada de Active Directory
MSI de Active Directory		 Autentícate usando una identidad administrada de Microsoft Entra, asignada por el sistema o por el usuario. 2.1.0+
Valor predeterminado de Active Directory Autentícate con una identidad de Microsoft Entra mediante mecanismos sin contraseña y no interactivos, como identidades administradas, Visual Studio Code, Visual Studio, la CLI de Azure, etc. 3.0.0+
Identidad de carga de trabajo de Active Directory Autentíquese con una identidad de Microsoft Entra mediante una identidad administrada asignada a un usuario federado para conectarse a SQL Database desde entornos de cliente de Azure que están habilitados para la identidad de la carga de trabajo. 5.2.0+

1 Antes de Microsoft.Data.SqlClient 2.0.0, los modos de autenticación Active Directory Integrated y Active Directory Interactive se admiten solo en .NET Framework.

Uso de la autenticación de contraseñas

El modo de autenticación Active Directory Password admite la autenticación en orígenes de datos de Azure con Microsoft Entra ID para usuarios nativos o federados de Microsoft Entra. Cuando se usa este modo, se deben proporcionar las credenciales de usuario en la cadena de conexión. En el ejemplo siguiente se muestra cómo usar la autenticación 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=<password>";

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

Uso de la autenticación integrada

Para usar el modo de autenticación Active Directory Integrated, debes tener una instancia de Active Directory local que esté unida a Microsoft Entra ID en la nube. Puedes realizar la federación mediante Servicios de federación de Active Directory (AD FS), por ejemplo.

Cuando haya iniciado sesión en un equipo unido a un dominio, puede acceder a los orígenes de datos de Azure SQL sin que se le soliciten las credenciales con este modo. No se puede especificar el nombre de usuario y la contraseña en la cadena de conexión para aplicaciones de .NET Framework. El nombre de usuario es opcional en la cadena de conexión para las aplicaciones de .NET Core y .NET Standard. No se puede establecer la propiedad Credential de SqlConnection en este modo.

El siguiente fragmento de código es un ejemplo de cuándo se está usando la autenticación 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();
}

Uso de la autenticación interactiva

La autenticación Active Directory Interactive admite la tecnología de autenticación multifactor para conectarse a orígenes de datos de Azure SQL. Si se proporciona este modo de autenticación en la cadena de conexión, aparece una pantalla de autenticación de Azure y solicita al usuario que escriba credenciales válidas. No se puede especificar la contraseña en la cadena de conexión.

No se puede establecer la propiedad Credential de SqlConnection en este modo. Con Microsoft.Data.SqlClient 2.0.0 y versiones posteriores, se permite el nombre de usuario en la cadena de conexión cuando está en modo interactivo.

En el ejemplo siguiente se muestra cómo usar la autenticación 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();
}

Uso de la autenticación de entidad de servicio

En el modo de autenticación Active Directory Service Principal, la aplicación cliente se puede conectar a orígenes de datos de Azure SQL proporcionando el identificador y el secreto de cliente de una identidad de entidad de servicio. La autenticación de la entidad de servicio implica lo siguiente:

  1. Configuración del registro de una aplicación con un secreto.
  2. Concesión de permisos a la aplicación en la instancia de Azure SQL Database.
  3. Conexión con la credencial correcta.

En el ejemplo siguiente se muestra cómo usar la autenticación 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=<password>";

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

Autenticación mediante flujo de códigos de dispositivo

Con la Biblioteca de autenticación de Microsoft para .NET (MSAL.NET), la autenticación Active Directory Device Code Flow permite a la aplicación cliente conectarse a orígenes de datos de Azure SQL desde dispositivos y sistemas operativos que no tienen un explorador web interactivo. La autenticación interactiva se realiza en otro dispositivo. Para obtener más información sobre la autenticación de flujo de código de dispositivo, consulte Flujo de concesión de autorización de dispositivo de OAuth 2.0.

Cuando este modo está en uso, no se puede establecer la propiedad Credential de SqlConnection. Además, el nombre de usuario y la contraseña no se deben especificar en la cadena de conexión.

El siguiente fragmento de código es un ejemplo del uso de la autenticación Active Directory Device Code Flow.

Nota:

El tiempo de espera de Active Directory Device Code Flow se establece de manera predeterminada en la opción Connect Timeout de la conexión. Asegúrese de especificar una variable Connect Timeout que proporcione tiempo suficiente para pasar por el flujo de autenticación del código del dispositivo.

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

Uso de la autenticación de identidad administrada

La autenticación con identidades administradas para recursos de Azure es el método de autenticación recomendado para el acceso mediante programación a SQL. Una aplicación cliente puede usar la identidad administrada asignada por el sistema o asignada por el usuario de un recurso para autenticarse en SQL con Microsoft Entra ID, proporcionando la identidad y usándola para obtener tokens de acceso. Este método elimina la necesidad de administrar las credenciales y los secretos, y puede simplificar la administración del acceso.

Hay dos tipos de identidades administradas:

  • La identidad administrada asignada por el sistema se crea como parte de un recurso de Azure (como la instancia administrada de SQL o el servidor lógico) y comparte el ciclo de vida de ese recurso. Las identidades administradas asignadas por el sistema solo se pueden asociar con un recurso de Azure.
  • La identidad administrada asignada por el usuario se crea como recurso de Azure independiente. Se puede asignar a una o varias instancias de un servicio de Azure.

Para más información sobre las identidades administradas, consulte ¿Qué son las identidades administradas para recursos de Azure?

A partir de Microsoft.Data.SqlClient 2.1.0, el controlador admite la autenticación en Azure SQL Database, Azure Synapse Analytics y Azure SQL Managed Instance mediante la adquisición de tokens de acceso a través de la identidad administrada. Para usar esta autenticación, especifique Active Directory Managed Identity o Active Directory MSI en la cadena de conexión; no se requiere ninguna contraseña. Tampoco puede establecer la propiedad Credential de SqlConnection en este modo.

En el caso de identidades administradas asignadas por el usuario, es necesario proporcionar el identificador de cliente de la identidad administrada cuando se usa Microsoft.Data.SqlClient v3.0 o versiones posteriores. Si usa Microsoft.Data.SqlClient v2.1, debe proporcionar el identificador de objeto de la identidad administrada.

En el ejemplo siguiente se muestra cómo usar la autenticación Active Directory Managed Identity con una identidad administrada asignada por el sistema.

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

En el ejemplo siguiente se muestra la autenticación de Active Directory Managed Identity con una identidad administrada asignada por el usuario con Microsoft.Data.SqlClient v3.0 y versiones posteriores.

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

En el ejemplo siguiente se muestra la autenticación de Active Directory Managed Identity con una identidad administrada asignada por el usuario con Microsoft.Data.SqlClient v2.1.

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

Uso de la autenticación predeterminada

Disponible a partir de la versión 3.0, este modo de autenticación amplía las posibilidades de autenticación de usuarios. Este modo amplía las soluciones de inicio de sesión al entorno de cliente, Visual Studio Code, Visual Studio, la CLI de Azure, etc.

Con este modo de autenticación, el controlador adquiere un token al pasar "DefaultAzureCredential" desde la biblioteca Azure Identity para adquirir un token de acceso. Este modo intenta usar un conjunto de tipos de credenciales por orden para adquirir un token de acceso. Según la versión de la biblioteca de Azure Identity utilizada, el conjunto de credenciales varía. Las diferencias específicas de la versión se indican en la lista. Para ver el comportamiento específico de la versión de Azure Identity, consulte la documentación de la API de Azure.Identity.

Importante

El valor predeterminado de Active Directory es una opción cómoda para simplificar las diferencias de cadena de conexión entre distintos entornos. Sin embargo, puede tener impactos en el rendimiento porque tiene que buscar en varios lugares la información de autenticación. Si ve velocidades de conexión lentas con Active Directory Default, use una opción de autenticación diferente destinada específicamente al método de autenticación que usa en su entorno. "Active Directory Default" no se recomienda para entornos que tienen estrictos niveles de servicio en tiempos de respuesta.

  • EnvironmentCredential
    • Habilita la autenticación con Microsoft Entra ID mediante el cliente y el secreto, o el nombre de usuario y la contraseña, y los detalles configurados en las siguientes variables de entorno: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME y AZURE_PASSWORD (más información)
  • WorkloadIdentityCredential
    • Habilita la autenticación de identidad de carga de trabajo de Microsoft Entra en Kubernetes y otros hosts que admiten identidades de carga de trabajo. Para obtener más información, consulte Microsoft Entra Workload ID. Disponible a partir de la versión 1.10 de Azure Identity y Microsoft.Data.SqlClient 5.1.4.
  • ManagedIdentityCredential
    • Intenta la autenticación con Microsoft Entra ID mediante una identidad administrada que se asigna al entorno de implementación. El valor "Client Id" de la "Identidad administrada asignada por el usuario" se lee desde la propiedad de conexión "User Id".
  • SharedTokenCacheCredential
    • Realiza la autenticación mediante tokens en la caché local compartida entre aplicaciones de Microsoft.
  • VisualStudioCredential
    • Permite la autenticación con Microsoft Entra ID mediante los datos de Visual Studio
  • VisualStudioCodeCredential
    • Permite la autenticación con Microsoft Entra ID mediante los datos de Visual Studio Code.
  • AzurePowerShellCredential
    • Permite la autenticación con Microsoft Entra ID mediante Azure PowerShell. Disponible a partir de la versión 1.6 de Azure Identity y Microsoft.Data.SqlClient 5.0.
  • AzureCliCredential
    • Habilita la autenticación con Microsoft Entra ID mediante la CLI de Azure para obtener un token de acceso.
  • AzureDeveloperCliCredential
    • Habilita la autenticación con Microsoft Entra ID mediante Azure Developer CLI para obtener un token de acceso. Disponible a partir de la versión 1.10 de Azure Identity y Microsoft.Data.SqlClient 5.1.4.

Nota:

InteractiveBrowserCredential está deshabilitado en la implementación del controlador de Active Directory Default y Active Directory Interactive es la única opción disponible para adquirir un token mediante la autenticación MFA/Interactiva.

Por el momento, no hay más opciones de personalización disponibles.

En el ejemplo siguiente se muestra cómo usar la autenticación de Valor predeterminado de 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();
}

Uso de Identity Authentication para cargas de trabajo

Disponible a partir de la versión 5.2, como con las identidades administradas, el modo de autenticación de la identidad de la carga de trabajo usa el valor del parámetro User ID en la cadena de conexión para su id. de cliente si se especifica. Pero a diferencia de la identidad administrada, WorkloadIdentityCredentialOptions tiene como valor predeterminado su valor de las variables de entorno: AZURE_TENANT_ID, AZURE_CLIENT_ID y AZURE_FEDERATED_TOKEN_FILE. Sin embargo, solo la cadena de conexión puede invalidar el Id. de cliente.

En el ejemplo siguiente se muestra la autenticación de Active Directory Workload Identity con una identidad administrada asignada por el usuario con Microsoft.Data.SqlClient v5.2 y versiones posteriores.

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

Personalización de la autenticación de Microsoft Entra

Además de usar la autenticación de Microsoft Entra integrada en el controlador, Microsoft. Data. SqlClient 2.1.0 y versiones posteriores proporcionan a las aplicaciones la opción de personalizar la autenticación de Microsoft Entra. La personalización se basa en la clase ActiveDirectoryAuthenticationProvider, que se deriva de la clase abstracta SqlAuthenticationProvider.

Durante la autenticación de Microsoft Entra, la aplicación cliente puede definir su propia clase ActiveDirectoryAuthenticationProvider con uno de estas dos opciones:

  • Usar un método de devolución de llamada personalizado.
  • Pasar un identificador de cliente de aplicación a la biblioteca MSAL a través del controlador SqlClient para obtener los tokens de acceso.

En el ejemplo siguiente se muestra cómo usar una devolución de llamada personalizada cuando la autenticación Active Directory Device Code Flow está en uso.

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

Con una clase ActiveDirectoryAuthenticationProvider personalizada, se puede pasar un identificador de cliente de aplicación definido por el usuario a SqlClient cuando se usa un modo de autenticación de Microsoft Entra compatible. Los modos de autenticación admitidos de Microsoft Entra incluyen Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principal y Active Directory Device Code Flow.

El identificador de cliente de la aplicación también se puede configurar a través de SqlAuthenticationProviderConfigurationSection o SqlClientAuthenticationProviderConfigurationSection. La propiedad de configuración applicationClientId se aplica a .NET Framework 4.6 + y .NET Core 2.1+.

El siguiente fragmento de código es un ejemplo del uso de una clase ActiveDirectoryAuthenticationProvider personalizada con un identificador de cliente de aplicación definido por el usuario cuando se está usando la autenticación 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!");
            }
        }
    }
}

En el ejemplo siguiente se muestra cómo establecer un identificador de cliente de aplicación a través de una sección de configuración.

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

Uso de AccessTokenCallback

Disponible en la versión 5.2 y las posteriores, hay una nueva propiedad AccessTokenCallback en SqlConnection. Use la propiedad AccessTokenCallback para definir una función personalizada que devuelva un token de acceso según los parámetros entrantes. Usar el callback es mejor que utilizar la propiedad AccessToken porque permite actualizar el token de acceso dentro de un grupo de conexiones. Al usar la propiedad AccessToken, el token no se puede actualizar después de abrir la conexión. Tampoco se ha proporcionado ninguna fecha de caducidad asociada a través de la propiedad. Una vez que expire el token, las nuevas solicitudes de conexión producirán un error de autenticación de servidor y los grupos que lo usan deberán borrarse manualmente.

Importante

Un AccessTokenCallback debe devolver tokens de acceso del mismo contexto de seguridad para los mismos parámetros de entrada. Si el contexto de seguridad es diferente, se puede devolver una conexión agrupada con el contexto de seguridad incorrecto para una solicitud de conexión.

Nota:

AccessTokenCallback forma parte de la clave que se usa para identificar grupos de conexiones. Evite crear una nueva devolución de llamada de función para cada creación de una instancia de SqlConnection, ya que esto da como resultado un nuevo grupo cada vez. Haga referencia a la misma instancia de una función para las conexiones que desea tener en cuenta para la agrupación. La clave del grupo de conexiones incluye los parámetros que se pasan al callback para particionar adecuadamente los grupos de conexiones.

El siguiente fragmento de código es un ejemplo de uso de la propiedad AccessTokenCallback en Microsoft.Data.SqlClient v5.2 y versiones posteriores.

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

Compatibilidad con un proveedor de autenticación de SQL personalizado

Dada la mayor flexibilidad, la aplicación cliente también puede usar su propio proveedor para la autenticación de Microsoft Entra en lugar de usar la clase ActiveDirectoryAuthenticationProvider. El proveedor de autenticación personalizado debe ser una subclase de SqlAuthenticationProvider con métodos invalidados. Después, debe registrar el proveedor personalizado, invalidando uno o varios de los métodos de autenticación Active Directory* existentes.

Importante

Un proveedor de autenticación debe devolver tokens de acceso del mismo contexto de seguridad para los mismos parámetros de entrada. Si el contexto de seguridad es diferente, se puede devolver una conexión agrupada con el contexto de seguridad incorrecto para una solicitud de conexión.

En el ejemplo siguiente se muestra cómo usar un nuevo proveedor de autenticación para la autenticación 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!");
            }
        }
    }
}

Además de mejorar la experiencia de autenticación de Active Directory Interactive, Microsoft.Data.SqlClient 2.1.0 y versiones posteriores proporcionan las siguientes API para que las aplicaciones cliente personalicen la autenticación interactiva y la autenticación del flujo de código de dispositivo.

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

Consulte también