Expose SSPI context provider as public

.github/instructions/api-design.instructions.md

@@ -27,12 +27,16 @@ Reference assemblies define the public contract:
 - Public and protected members
 - Method signatures (no implementation)
 
+### Nullable Annotations
+The reference assemblies do **not** use C# nullable context (`#nullable enable`). All reference types in `ref/` files must be declared as non-nullable (e.g., `string` not `string?`), even when the implementation uses nullable annotations. This is a project-wide convention — do not add `?` nullable annotations to ref assembly signatures.
+
 ### Updating Public APIs
 When adding or modifying public APIs:
 1. Update reference assembly in BOTH `netcore/ref/` and `netfx/ref/`
 2. Ensure signatures match across platforms
 3. Add XML documentation
 4. Consider backward compatibility
+5. Do not use nullable annotations (`?`) in ref assemblies (see above)
 
 ## ADO.NET Interface Compliance
 

doc/samples/SspiContextProvider_CustomProvider.cs

@@ -0,0 +1,55 @@
+// <Snippet1>
+using System;
+using System.Buffers;
+using System.Net.Security;
+using Microsoft.Data.SqlClient;
+
+// Custom SSPI context provider that uses NegotiateAuthentication
+// to perform SSPI authentication with a SQL Server.
+class CustomSspiContextProvider : SspiContextProvider
+{
+    private NegotiateAuthentication? _auth;
+
+    protected override bool GenerateContext(
+        ReadOnlySpan<byte> incomingBlob,
+        IBufferWriter<byte> outgoingBlobWriter,
+        SspiAuthenticationParameters authParams)
+    {
+        // Initialize the NegotiateAuthentication on first call
+        _auth ??= new NegotiateAuthentication(
+            new NegotiateAuthenticationClientOptions
+            {
+                Package = "Negotiate",
+                TargetName = authParams.Resource,
+            });
+
+        // Generate the next authentication token
+        NegotiateAuthenticationStatusCode statusCode;
+        byte[]? blob = _auth.GetOutgoingBlob(incomingBlob, out statusCode);
+
+        if (statusCode is not NegotiateAuthenticationStatusCode.Completed
+            and not NegotiateAuthenticationStatusCode.ContinueNeeded)
+        {
+            return false;
+        }
+
+        if (blob is not null)
+        {
+            outgoingBlobWriter.Write(blob);
+        }
+
+        return true;
+    }
+}
+
+class Program
+{
+    static void Main()
+    {
+        using var connection = new SqlConnection("Server=myServer;Integrated Security=true;");
+        connection.SspiContextProvider = new CustomSspiContextProvider();
+        connection.Open();
+        Console.WriteLine("Connected successfully with custom SSPI provider.");
+    }
+}
+// </Snippet1>

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:Microsoft.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">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

@@ -150,6 +150,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

@@ -829,6 +829,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; } }
@@ -1876,6 +1878,39 @@ 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"]/ctor/*'/>
+        protected 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/netfx/ref/Microsoft.Data.SqlClient.cs

@@ -708,6 +708,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; } }
@@ -1857,6 +1859,39 @@ 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"]/ctor/*'/>
+        protected 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/src/Microsoft/Data/SqlClient/SSPI/SspiAuthenticationParameters.cs

@@ -6,22 +6,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

@@ -11,7 +11,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!;
@@ -21,6 +22,7 @@ internal abstract class SspiContextProvider
 
         private protected TdsParserStateObject _physicalStateObj = null!;
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="SspiContextProvider"]/ctor/*'/>
         protected SspiContextProvider()
         {
         }
@@ -67,6 +69,7 @@ private protected virtual void Initialize()
         {
         }
 
+        /// <include file='../../../../../../../doc/snippets/Microsoft.Data.SqlClient/SspiContextProvider.xml' path='docs/members[@name="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/src/Microsoft/Data/SqlClient/SqlConnection.cs

@@ -795,11 +795,18 @@ 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
             {
+                // If a connection is connecting or is ever opened, SspiContextProvider cannot be set
+                if (!InnerConnection.AllowSetConnectionString)
+                {
+                    throw ADP.OpenConnectionPropertySet(nameof(SspiContextProvider), InnerConnection.State);
+                }
+
                 ConnectionString_Set(new SqlConnectionPoolKey(_connectionString, credential: _credential, accessToken: null, accessTokenCallback: null, sspiContextProvider: value));
                 _sspiContextProvider = value;
             }