Expose authentication configuration handlers from Abstractions

BUILDGUIDE.md

@@ -56,6 +56,24 @@ package the project. The `build.proj` file provides convenient targets to accomp
 > This section is not exhaustive of all targets or parameters to `build.proj`. Complete documentation is available in
 > [`build.proj`](build.proj).
 
+### Authentication configuration compatibility checks
+
+The executable fixtures under `src/Microsoft.Data.SqlClient/tests/AuthenticationTests/`
+run in separate processes to validate both current and legacy app.config section
+declarations, their forwarded handler types, initializer activation and configured
+provider precedence, without SQL Server or identity-service access.
+
+```bash
+dotnet build build.proj -t:TestAuthenticationConfiguration -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Project
+dotnet build build.proj -t:TestAuthenticationConfiguration -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Package
+```
+
+Package mode prepares local packages unless `-p:SkipDependencyPack=true` is supplied.
+Use `-p:PackageVersionSqlClient=<version>` for prebuilt packages and an isolated
+`NUGET_PACKAGES` directory when validating package changes to avoid stale cache entries.
+On Windows, select `-p:TestFramework=net462` to execute .NET Framework checks.
+Cross-building .NET Framework on Linux does not execute those scenarios.
+
 ### Building Projects
 
 From the root of your repository, run `dotnet build` against `build.proj` with a build target, following this pattern:

build.proj

@@ -604,13 +604,25 @@
     <SqlClientFunctionalTestProjectPath>$(SqlClientSrcRoot)tests/FunctionalTests/Microsoft.Data.SqlClient.FunctionalTests.csproj</SqlClientFunctionalTestProjectPath>
     <SqlClientManualTestProjectPath>$(SqlClientSrcRoot)tests/ManualTests/Microsoft.Data.SqlClient.ManualTests.csproj</SqlClientManualTestProjectPath>
     <SqlClientUnitTestProjectPath>$(SqlClientSrcRoot)tests/UnitTests/Microsoft.Data.SqlClient.UnitTests.csproj</SqlClientUnitTestProjectPath>
+    <AuthenticationTestsScript>$(SqlClientSrcRoot)tests/AuthenticationTests/RunAuthenticationTests.ps1</AuthenticationTestsScript>
 
     <!-- Tools/Specs Paths -->
     <GenApiPath>$(RepoRoot)tools/GenAPI/Microsoft.DotNet.GenAPI/</GenApiPath>
     <GenApiProjectPath>$(GenApiPath)Microsoft.DotNet.GenAPI.csproj</GenApiProjectPath>
   </PropertyGroup>
 
   <!-- Build SqlClient Targets =============================================== -->
+  <PropertyGroup>
+    <AuthenticationTestFramework Condition="'$(TestFramework)' != ''">$(TestFramework)</AuthenticationTestFramework>
+    <AuthenticationTestFramework Condition="'$(AuthenticationTestFramework)' == ''">net10.0</AuthenticationTestFramework>
+    <AuthenticationPackageVersionArgument Condition="'$(PackageVersionSqlClient)' != ''">-PackageVersionSqlClient "$(PackageVersionSqlClient)"</AuthenticationPackageVersionArgument>
+    <TestAuthenticationConfigurationDependsOn Condition="'$(ReferenceType)' == 'Package' AND '$(SkipDependencyPack)' != 'true'">PackSqlClient</TestAuthenticationConfigurationDependsOn>
+  </PropertyGroup>
+  <Target Name="TestAuthenticationConfiguration" DependsOnTargets="$(TestAuthenticationConfigurationDependsOn)">
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; tool run pwsh -- -NonInteractive -NoProfile -File &quot;$(AuthenticationTestsScript)&quot; -Framework $(AuthenticationTestFramework) -ReferenceType $(ReferenceType) -Configuration $(Configuration) $(AuthenticationPackageVersionArgument)"
+          WorkingDirectory="$(RepoRoot)" />
+  </Target>
+
   <!-- BuildSqlClient: Builds all binaries for SqlClient -->
   <Target Name="BuildSqlClient" DependsOnTargets="BuildSqlClientImpl;BuildSqlClientRef;BuildSqlClientNotSupported" />
 
@@ -865,7 +877,7 @@
     </PropertyGroup>
     <Message Importance="High" Text=">>> Running manual tests for SqlClient"/>
     <Message Text="    Command: $(DotnetCommand)"/>
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- TestSqlClientUnit: Runs unit tests for SqlClient -->
@@ -894,7 +906,7 @@
     </PropertyGroup>
     <Message Importance="High" Text=">>> Running unit tests for SqlClient"/>
     <Message Text="    Command: $(DotnetCommand)"/>
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- ================================================================= -->

doc/samples/SqlAuthenticationProviders.config

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Licensed to the .NET Foundation under one or more agreements.
+  The .NET Foundation licenses this file to you under the MIT license.
+  See the LICENSE file in the project root for more information.
+-->
+<!--
+  Merge into an application's app.config. The public handler lives in Abstractions
+  and is forwarded from SqlClient, preserving this assembly-qualified name.
+  Replace the provider type with an application-defined SqlAuthenticationProvider.
+-->
+<configuration>
+  <configSections>
+    <section name="SqlClientAuthenticationProviders"
+             type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
+  </configSections>
+  <SqlClientAuthenticationProviders>
+    <providers>
+      <add name="active directory default" type="ExampleAuthenticationProvider, ExampleApp" />
+    </providers>
+  </SqlClientAuthenticationProviders>
+</configuration>

src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/Abstractions.csproj

@@ -78,6 +78,8 @@
                       Condition="'$(ReferenceType)' == 'Project'" />
     <PackageReference Include="Microsoft.Data.SqlClient.Internal.Logging"
                       Condition="'$(ReferenceType)' == 'Package'" />
+    <PackageReference Include="System.Configuration.ConfigurationManager"
+                      PrivateAssets="contentfiles;build;buildTransitive;analyzers" />
   </ItemGroup>
 
   <!-- CodeGen Targets ================================================= -->

src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/PackageReadme.md

@@ -18,6 +18,23 @@ This package supports:
 
 - .NET Standard 2.0 (compatible with .NET Framework 4.6.1+, .NET Core 2.0+, and .NET 5+)
 
+## Authentication configuration
+
+The public `SqlAuthenticationProviderConfigurationSection` (legacy
+`SqlAuthenticationProviders`) and `SqlClientAuthenticationProviderConfigurationSection`
+(`SqlClientAuthenticationProviders`) handlers are defined in this package and forwarded
+from SqlClient. Existing app.config section declarations naming `Microsoft.Data.SqlClient`
+remain valid. Section names, properties (`providers`, `initializerType`,
+`applicationClientId`, `useWamBroker`) and empty defaults are unchanged.
+
+`System.Configuration.ConfigurationManager` is a transitive compile dependency, so
+consumers can use the handlers and their configuration base types without adding a
+separate package reference. Authentication initialization and provider loading remain
+in the driver.
+
+See the repository's `doc/samples/SqlAuthenticationProviders.config` for a section
+declaration and custom provider example.
+
 ## Installation
 
 Install the package via NuGet:

src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/SqlAuthenticationProviderConfigurationSection.cs

@@ -0,0 +1,39 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Configuration;
+
+namespace Microsoft.Data.SqlClient
+{
+    /// <summary>Defines the legacy SqlAuthenticationProviders section for authentication configuration in app.config.</summary>
+    public class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
+    {
+        /// <summary>The name of the legacy authentication configuration section.</summary>
+        public const string Name = "SqlAuthenticationProviders";
+
+        /// <summary>Gets the user-defined authentication providers.</summary>
+        [ConfigurationProperty("providers")]
+        public ProviderSettingsCollection Providers => (ProviderSettingsCollection)this["providers"];
+
+        /// <summary>Gets the assembly-qualified initializer type name, or an empty string when unset.</summary>
+        [ConfigurationProperty("initializerType")]
+        public string InitializerType => this["initializerType"] as string ?? string.Empty;
+
+        /// <summary>Gets the application client ID, or an empty string when unset.</summary>
+        [ConfigurationProperty("applicationClientId", IsRequired = false)]
+        public string ApplicationClientId => this["applicationClientId"] as string ?? string.Empty;
+
+        /// <summary>Gets the Windows Authentication Manager broker preference, or an empty string when unset.</summary>
+        /// <remarks>The value is a string to distinguish an unset preference from an explicit false value.</remarks>
+        [ConfigurationProperty("useWamBroker", IsRequired = false)]
+        public string UseWamBroker => this["useWamBroker"] as string ?? string.Empty;
+    }
+
+    /// <summary>Defines the current SqlClientAuthenticationProviders section for authentication configuration in app.config.</summary>
+    public class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
+    {
+        /// <summary>The name of the current authentication configuration section.</summary>
+        public new const string Name = "SqlClientAuthenticationProviders";
+    }
+}

src/Microsoft.Data.SqlClient.slnx

@@ -202,6 +202,9 @@
       <Platform Solution="*|x86" Project="x86" />
     </Project>
   </Folder>
+  <Folder Name="/test/AuthenticationTests/">
+    <Project Path="Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/ConfigurationTest.csproj" />
+  </Folder>
   <Folder Name="/test/Stress/">
     <Project Path="Microsoft.Data.SqlClient/tests/StressTests/IMonitorLoader/IMonitorLoader.csproj" />
     <Project Path="Microsoft.Data.SqlClient/tests/StressTests/SqlClient.Stress.Common/SqlClient.Stress.Common.csproj" />

src/Microsoft.Data.SqlClient/notsupported/Microsoft.Data.SqlClient.csproj

@@ -105,6 +105,10 @@
   </PropertyGroup>
 
   <!-- References ====================================================== -->
+  <ItemGroup>
+    <!-- GenAPI does not reproduce forwards from the reference assembly. -->
+    <Compile Include="../src/TypeForwards.Abstractions.cs" Link="TypeForwards.Abstractions.cs" />
+  </ItemGroup>
   <!--
     Reference the ref project to cause it to be built, so we can use it as the contract to build
     not supported assemblies against. Note, this must be set to output item type of none otherwise

src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj

@@ -155,6 +155,9 @@
   </Target>
 
   <!-- References ====================================================== -->
+  <ItemGroup>
+    <Compile Include="../src/TypeForwards.Abstractions.cs" Link="TypeForwards.Abstractions.cs" />
+  </ItemGroup>
   <!-- Reference to Abstractions -->
   <ItemGroup>
     <ProjectReference Include="$(RepoRoot)src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/Abstractions.csproj"

src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.nuspec

@@ -64,7 +64,7 @@
         <dependency id="Microsoft.IdentityModel.JsonWebTokens" version="8.23.0" />
         <dependency id="Microsoft.IdentityModel.Protocols.OpenIdConnect" version="8.23.0" />
         <dependency id="Microsoft.SqlServer.Server" version="$SqlServerVersionRange$" />
-        <dependency id="System.Configuration.ConfigurationManager" version="10.0.12" exclude="Compile" />
+        <dependency id="System.Configuration.ConfigurationManager" version="10.0.12" />
         <dependency id="System.Security.Cryptography.Pkcs" version="10.0.12" />
         <dependency id="System.Threading.RateLimiting" version="10.0.12" />
       </group>
@@ -78,7 +78,7 @@
         <dependency id="Microsoft.IdentityModel.JsonWebTokens" version="8.23.0" />
         <dependency id="Microsoft.IdentityModel.Protocols.OpenIdConnect" version="8.23.0" />
         <dependency id="Microsoft.SqlServer.Server" version="$SqlServerVersionRange$" />
-        <dependency id="System.Configuration.ConfigurationManager" version="10.0.12" exclude="Compile" />
+        <dependency id="System.Configuration.ConfigurationManager" version="10.0.12" />
         <dependency id="System.Security.Cryptography.Pkcs" version="10.0.12" />
         <dependency id="System.Text.Json" version="10.0.12" />
         <dependency id="System.Threading.Channels" version="10.0.12" />

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlAuthenticationProviderManager.cs

@@ -578,49 +578,6 @@ private static string GetProviderType(SqlAuthenticationProvider? provider)
         }
     }
 
-    /// <summary>
-    /// The configuration section definition for reading app.config.
-    /// </summary>
-    internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
-    {
-        public const string Name = "SqlAuthenticationProviders";
-
-        /// <summary>
-        /// User-defined auth providers.
-        /// </summary>
-        [ConfigurationProperty("providers")]
-        public ProviderSettingsCollection Providers => (ProviderSettingsCollection)this["providers"];
-
-        /// <summary>
-        /// User-defined initializer.
-        /// </summary>
-        [ConfigurationProperty("initializerType")]
-        public string InitializerType => this["initializerType"] as string ?? string.Empty;
-
-        /// <summary>
-        /// Application Client Id
-        /// </summary>
-        [ConfigurationProperty("applicationClientId", IsRequired = false)]
-        public string ApplicationClientId => this["applicationClientId"] as string ?? string.Empty;
-
-        /// <summary>
-        /// Forwarded to <c>ActiveDirectoryAuthenticationProviderOptions.UseWamBroker</c>
-        /// when the Azure extension's default provider is auto-installed. Stored as a string so
-        /// that an unset attribute can be distinguished from <c>useWamBroker="false"</c>; the
-        /// runtime parses it with <see cref="bool.TryParse(string, out bool)"/>.
-        /// </summary>
-        [ConfigurationProperty("useWamBroker", IsRequired = false)]
-        public string UseWamBroker => this["useWamBroker"] as string ?? string.Empty;
-    }
-
-    /// <summary>
-    /// The configuration section definition for reading app.config.
-    /// </summary>
-    internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
-    {
-        public new const string Name = "SqlClientAuthenticationProviders";
-    }
-
     /// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlAuthenticationInitializer.xml' path='docs/members[@name="SqlAuthenticationInitializer"]/SqlAuthenticationInitializer/*'/>
     public abstract class SqlAuthenticationInitializer
     {

src/Microsoft.Data.SqlClient/src/TypeForwards.Abstractions.cs

@@ -7,3 +7,5 @@
 [assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.Data.SqlClient.SqlAuthenticationProvider))]
 [assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.Data.SqlClient.SqlAuthenticationProviderException))]
 [assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.Data.SqlClient.SqlAuthenticationToken))]
+[assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection))]
+[assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection))]

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/ConfigurationTest.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <AssemblyName>AuthenticationConfigurationTest</AssemblyName>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net462;net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+  <ItemGroup Condition="'$(ReferenceType)' == 'Project'">
+    <ProjectReference Include="$(RepoRoot)src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj" />
+  </ItemGroup>
+  <ItemGroup Condition="'$(ReferenceType)' == 'Package'">
+    <PackageReference Include="Microsoft.Data.SqlClient" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Update="*.config" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+</Project>

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/Program.cs

@@ -0,0 +1,57 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Microsoft.Data.SqlClient;
+using System.Configuration;
+
+string scenario = args.Single();
+string sectionName = scenario switch
+{
+    "configured" => "SqlClientAuthenticationProviders",
+    "legacy" => "SqlAuthenticationProviders",
+    _ => throw new ArgumentException("Unknown configuration scenario: " + scenario)
+};
+
+var section = ConfigurationManager.GetSection(sectionName) as SqlAuthenticationProviderConfigurationSection
+    ?? throw new InvalidOperationException("The section declaration did not resolve.");
+ConfigurationSection configurationSection = section;
+Require(configurationSection.ElementInformation.Properties.Count == 4 && section.Providers.Count == 1,
+    "The public configuration schema did not compile or load through its transitive dependencies.");
+Require(section.GetType().Assembly.GetName().Name == "Microsoft.Data.SqlClient.Extensions.Abstractions",
+    "The assembly-qualified handler was not forwarded to Abstractions.");
+Require(SqlAuthenticationProvider.GetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive) is TestProvider,
+    "The driver's typed section retrieval did not load the configured provider.");
+Require(TestInitializer.Initialized, "The configured driver initializer did not run.");
+Require(!SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, new TestProvider()),
+    "Application registration replaced the configured provider.");
+Console.WriteLine("PASS: " + scenario);
+
+/// <summary>Fails the executable scenario when its required compatibility contract is not preserved.</summary>
+static void Require(bool condition, string message)
+{
+    if (!condition)
+    {
+        throw new InvalidOperationException(message);
+    }
+}
+
+/// <summary>Proves initializer activation still uses the driver-owned type in this intermediate layer.</summary>
+public sealed class TestInitializer : SqlAuthenticationInitializer
+{
+    public static bool Initialized;
+
+    /// <inheritdoc />
+    public override void Initialize() => Initialized = true;
+}
+
+/// <summary>Registers a provider without contacting an identity service or a database.</summary>
+public sealed class TestProvider : SqlAuthenticationProvider
+{
+    /// <inheritdoc />
+    public override bool IsSupported(SqlAuthenticationMethod method) => true;
+
+    /// <inheritdoc />
+    public override Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters) =>
+        throw new NotSupportedException();
+}

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/app.config

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <configSections>
+    <section name="SqlClientAuthenticationProviders"
+             type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
+  </configSections>
+  <SqlClientAuthenticationProviders initializerType="TestInitializer, AuthenticationConfigurationTest">
+    <providers>
+      <add name="active directory interactive" type="TestProvider, AuthenticationConfigurationTest" />
+    </providers>
+  </SqlClientAuthenticationProviders>
+</configuration>

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/legacy.config

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <configSections>
+    <section name="SqlAuthenticationProviders"
+             type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
+  </configSections>
+  <SqlAuthenticationProviders initializerType="TestInitializer, AuthenticationConfigurationTest">
+    <providers>
+      <add name="active directory interactive" type="TestProvider, AuthenticationConfigurationTest" />
+    </providers>
+  </SqlAuthenticationProviders>
+</configuration>