Expose SSPI context provider as public

doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml

@@ -2133,6 +2133,19 @@ The following sample tries to open a connection to an invalid database to simula
         Returns 0 if the connection is inactive on the client side.
       </remarks>
     </ServerProcessId>
+    <SspiContextProvider>
+      <summary>
+        Gets or sets the <see cref="SspiContextProvider"/> instance for customizing the SSPI context. If not set, the default for the platform will be used.
+      </summary>
+      <value>
+        An <see cref="T:Micorosft.Data.SqlClient.SspiContextProvider" /> instance.
+      </value>
+      <remarks>
+        <para>
+          The SspiContextProvider is a part of the connection pool key. Care should be taken when using this property to ensure the implementation returns a stable identity per resource.
+        </para>
+      </remarks>
+    </SspiContextProvider>
     <State>
       <summary>
         Indicates the state of the <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> during the most recent network operation performed on the connection.

doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<docs>
+  <members name="SspiAuthenticationParameters">
+    <SspiAuthenticationParameters>
+      <summary>Provides parameters used during SSPI authentication.</summary>
+    </SspiAuthenticationParameters>
+    <ctor>
+      <summary>Creates an instance of the SspiAuthenticationParameters.</summary>
+      <param name="serverName">The name of the server.</param>
+      <param name="resource">The resource (often the server service principal name).</param>
+    </ctor>
+    <Resource>
+      <summary>Gets the resource (often the server service principal name).</summary>
+    </Resource>
+    <ServerName>
+      <summary>Gets the server name.</summary>
+    </ServerName>
+    <UserId>
+      <summary>Gets or sets the user id if available.</summary>
+    </UserId>
+    <DatabaseName>
+      <summary>Gets or sets the database name if available.</summary>
+    </DatabaseName>
+    <Password>
+      <summary>Gets or sets the password if available.</summary>
+    </Password>
+  </members>
+</docs>

doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<docs>
+  <members name="SspiContextProvider">
+    <SspiContextProvider>
+      <summary>Provides the ability to customize SSPI context generation.</summary>
+    </SspiContextProvider>
+    <ctor>
+      <summary>Creates an instance of the SSPIContextProvider.</summary>
+    </ctor>
+    <GenerateContext>
+      <summary>Generates an SSPI outgoing blob given the incoming blob.</summary>
+      <param name="incomingBlob">Incoming blob</param>
+      <param name="outgoingBlobWriter">Outgoing blob</param>
+      <param name="authParams">Gets the authentication parameters associated with this connection.</param>
+      <returns>
+        <c>true</c> if the context was generated, otherwise <c>false</c>.
+      </returns>
+    </GenerateContext>
+  </members>
+</docs>

src/Microsoft.Data.SqlClient.sln

@@ -149,6 +149,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Microsoft.Data.SqlClient",
 		..\doc\snippets\Microsoft.Data.SqlClient\SqlRowUpdatingEventArgs.xml = ..\doc\snippets\Microsoft.Data.SqlClient\SqlRowUpdatingEventArgs.xml
 		..\doc\snippets\Microsoft.Data.SqlClient\SqlRowUpdatingEventHandler.xml = ..\doc\snippets\Microsoft.Data.SqlClient\SqlRowUpdatingEventHandler.xml
 		..\doc\snippets\Microsoft.Data.SqlClient\SqlTransaction.xml = ..\doc\snippets\Microsoft.Data.SqlClient\SqlTransaction.xml
+		..\doc\snippets\Microsoft.Data.SqlClient\SspiAuthenticationParameters.xml = ..\doc\snippets\Microsoft.Data.SqlClient\SspiAuthenticationParameters.xml
+		..\doc\snippets\Microsoft.Data.SqlClient\SspiContextProvider.xml = ..\doc\snippets\Microsoft.Data.SqlClient\SspiContextProvider.xml
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Microsoft.Data.SqlClient.DataClassification", "Microsoft.Data.SqlClient.DataClassification", "{5D1F0032-7B0D-4FB6-A969-FCFB25C9EA1D}"

src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.cs

@@ -929,6 +929,8 @@ public void RegisterColumnEncryptionKeyStoreProvidersOnConnection(System.Collect
         [System.ComponentModel.BrowsableAttribute(false)]
         [System.ComponentModel.DesignerSerializationVisibilityAttribute(0)]
         public Microsoft.Data.SqlClient.SqlCredential Credential { get { throw null; } set { } }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml' path='docs/members[@name="SqlConnection"]/SspiContextProvider/*' />
+        public SspiContextProvider SspiContextProvider { get { throw null; } set { } }
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml' path='docs/members[@name="SqlConnection"]/Database/*'/>
         [System.ComponentModel.DesignerSerializationVisibilityAttribute(0)]
         public override string Database { get { throw null; } }
@@ -1976,6 +1978,37 @@ public sealed class SqlConfigurableRetryFactory
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConfigurableRetryFactory.xml' path='docs/members[@name="SqlConfigurableRetryFactory"]/CreateNoneRetryProvider/*' />
         public static SqlRetryLogicBaseProvider CreateNoneRetryProvider() { throw null; }
     }
+    /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/SspiContextProvider/*'/>
+    public abstract class SspiContextProvider
+    {
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/GenerateContext/*'/>
+        protected abstract bool GenerateContext(System.ReadOnlySpan<byte> incomingBlob, System.Buffers.IBufferWriter<byte> outgoingBlobWriter, SspiAuthenticationParameters authParams);
+    }
+    /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/*'/>
+    public sealed class SspiAuthenticationParameters
+    {
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/ctor'/>
+        public SspiAuthenticationParameters(string serverName, string resource)
+        {
+            ServerName = serverName;
+            Resource = resource;
+        }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/Resource'/>
+        public string Resource { get; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/ServerName'/>
+        public string ServerName { get; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/UserId'/>
+        public string UserId { get; set; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/DatabaseName'/>
+        public string DatabaseName { get; set; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/Password'/>
+        public string Password { get; set; }
+    }
 }
 namespace Microsoft.Data.SqlClient.Diagnostics
 {

src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnection.cs

@@ -729,7 +729,8 @@ public Func<SqlAuthenticationParameters, CancellationToken, Task<SqlAuthenticati
             }
         }
 
-        internal SspiContextProvider SspiContextProvider
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml' path='docs/members[@name="SqlConnection"]/SspiContextProvider/*' />
+        public SspiContextProvider SspiContextProvider
         {
             get { return _sspiContextProvider; }
             set

src/Microsoft.Data.SqlClient/netfx/ref/Microsoft.Data.SqlClient.cs

@@ -810,6 +810,8 @@ public SqlConnection(string connectionString, Microsoft.Data.SqlClient.SqlCreden
         [System.ComponentModel.BrowsableAttribute(false)]
         [System.ComponentModel.DesignerSerializationVisibilityAttribute(0)]
         public Microsoft.Data.SqlClient.SqlCredential Credential { get { throw null; } set { } }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml' path='docs/members[@name="SqlConnection"]/SspiContextProvider/*' />
+        public SspiContextProvider SspiContextProvider { get { throw null; } set { } }
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml' path='docs/members[@name="SqlConnection"]/Database/*'/>
         [System.ComponentModel.DesignerSerializationVisibilityAttribute(0)]
         public override string Database { get { throw null; } }
@@ -1959,6 +1961,37 @@ public sealed class SqlConfigurableRetryFactory
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConfigurableRetryFactory.xml' path='docs/members[@name="SqlConfigurableRetryFactory"]/CreateNoneRetryProvider/*' />
         public static SqlRetryLogicBaseProvider CreateNoneRetryProvider() { throw null; }
     }
+    /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/SspiContextProvider/*'/>
+    public abstract class SspiContextProvider
+    {
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/GenerateContext/*'/>
+        protected abstract bool GenerateContext(System.ReadOnlySpan<byte> incomingBlob, System.Buffers.IBufferWriter<byte> outgoingBlobWriter, SspiAuthenticationParameters authParams);
+    }
+    /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/*'/>
+    public sealed class SspiAuthenticationParameters
+    {
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/ctor'/>
+        public SspiAuthenticationParameters(string serverName, string resource)
+        {
+            ServerName = serverName;
+            Resource = resource;
+        }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/Resource'/>
+        public string Resource { get; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/ServerName'/>
+        public string ServerName { get; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/UserId'/>
+        public string UserId { get; set; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/DatabaseName'/>
+        public string DatabaseName { get; set; }
+
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/Password'/>
+        public string Password { get; set; }
+    }
 }
 namespace Microsoft.Data.SqlClient.Server
 {

src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnection.cs

@@ -579,7 +579,8 @@ internal int ConnectRetryInterval
             get => ((SqlConnectionString)ConnectionOptions).ConnectRetryInterval;
         }
 
-        internal SspiContextProvider SspiContextProvider
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml' path='docs/members[@name="SqlConnection"]/SspiContextProvider/*' />
+        public SspiContextProvider SspiContextProvider
         {
             get { return _sspiContextProvider; }
             set

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SSPI/SspiAuthenticationParameters.cs

@@ -2,22 +2,29 @@
 
 namespace Microsoft.Data.SqlClient
 {
-    internal sealed class SspiAuthenticationParameters
+    /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/*'/>
+    public sealed class SspiAuthenticationParameters
     {
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/ctor'/>
         public SspiAuthenticationParameters(string serverName, string resource)
         {
             ServerName = serverName;
             Resource = resource;
         }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/Resource'/>
         public string Resource { get; }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/ServerName'/>
         public string ServerName { get; }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/UserId'/>
         public string? UserId { get; set; }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/DatabaseName'/>
         public string? DatabaseName { get; set; }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiAuthenticationParameters.xml' path='docs/members[@name="SspiAuthenticationParameters"]/SspiAuthenticationParameters/Password'/>
         public string? Password { get; set; }
     }
 }

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SSPI/SspiContextProvider.cs

@@ -6,7 +6,8 @@
 
 namespace Microsoft.Data.SqlClient
 {
-    internal abstract class SspiContextProvider
+    /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/SspiContextProvider/*'/>
+    public abstract class SspiContextProvider
     {
         private TdsParser _parser = null!;
         private ServerInfo _serverInfo = null!;
@@ -16,6 +17,7 @@ internal abstract class SspiContextProvider
 
         private protected TdsParserStateObject _physicalStateObj = null!;
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/SspiContextProvider/*'/>
         protected SspiContextProvider()
         {
         }
@@ -62,6 +64,7 @@ private protected virtual void Initialize()
         {
         }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/SspiContextProvider/GenerateContext'/>
         protected abstract bool GenerateContext(ReadOnlySpan<byte> incomingBlob, IBufferWriter<byte> outgoingBlobWriter, SspiAuthenticationParameters authParams);
 
         internal void WriteSSPIContext(ReadOnlySpan<byte> receivedBuff, IBufferWriter<byte> outgoingBlobWriter)

src/Microsoft.Data.SqlClient/tests/ManualTests/SQL/IntegratedAuthenticationTest/IntegratedAuthenticationTest.cs

@@ -2,6 +2,8 @@
 // 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;
+using System.Buffers;
 using Xunit;
 
 namespace Microsoft.Data.SqlClient.ManualTesting.Tests
@@ -56,12 +58,63 @@ public static void IntegratedAuthenticationTest_ServerSPN()
             TryOpenConnectionWithIntegratedAuthentication(builder.ConnectionString);
         }
 
+        [ConditionalFact(nameof(IsIntegratedSecurityEnvironmentSet), nameof(AreConnectionStringsSetup))]
+        public static void CustomSspiContextGeneratorTest()
+        {
+            SqlConnectionStringBuilder builder = new(DataTestUtility.TCPConnectionString);
+            builder.IntegratedSecurity = true;
+            Assert.True(DataTestUtility.ParseDataSource(builder.DataSource, out string hostname, out int port, out string instanceName));
+            // Build the SPN for the server we are connecting to
+            builder.ServerSPN = $"MSSQLSvc/{DataTestUtility.GetMachineFQDN(hostname)}";
+            if (!string.IsNullOrWhiteSpace(instanceName))
+            {
+                builder.ServerSPN += ":" + instanceName;
+            }
+
+            using SqlConnection conn = new(builder.ConnectionString)
+            {
+                SspiContextProvider = new TestSspiContextProvider(),
+            };
+
+            try
+            {
+                conn.Open();
+
+                Assert.Fail("Expected to use custom SSPI context provider");
+            }
+            catch (SspiTestException sspi)
+            {
+                Assert.Equal(sspi.AuthParams.ServerName, builder.DataSource);
+                Assert.Equal(sspi.AuthParams.DatabaseName, builder.InitialCatalog);
+                Assert.Equal(sspi.AuthParams.UserId, builder.UserID);
+                Assert.Equal(sspi.AuthParams.Password, builder.Password);
+            }
+        }
+
         private static void TryOpenConnectionWithIntegratedAuthentication(string connectionString)
         {
             using (SqlConnection connection = new SqlConnection(connectionString))
             {
                 connection.Open();
             }
         }
+
+        private sealed class TestSspiContextProvider : SspiContextProvider
+        {
+            protected override bool GenerateContext(ReadOnlySpan<byte> incomingBlob, IBufferWriter<byte> outgoingBlobWriter, SspiAuthenticationParameters authParams)
+            {
+                throw new SspiTestException(authParams);
+            }
+        }
+
+        private sealed class SspiTestException : Exception
+        {
+            public SspiTestException(SspiAuthenticationParameters authParams)
+            {
+                AuthParams = authParams;
+            }
+
+            public SspiAuthenticationParameters AuthParams { get; }
+        }
     }
 }