Introduce support for AAD Device Code Flow authentication

doc/samples/AADAuthenticationCustomDeviceFlowCallback.cs

@@ -0,0 +1,30 @@
+//<Snippet1>
+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 Task CustomDeviceFlowCallback(DeviceCodeResult result)
+        {
+            // Provide custon logic to process result information and read device code.
+            Console.WriteLine(result.Message);
+            return Task.FromResult(0);
+        }
+    }
+}
+//</Snippet1>

doc/samples/CustomDeviceCodeFlowAzureAuthenticationProvider.cs

@@ -0,0 +1,56 @@
+//<Snippet1>
+using System;
+using System.Threading.Tasks;
+using Microsoft.Identity.Client;
+using Microsoft.Data.SqlClient;
+
+namespace CustomAuthenticationProviderExamples
+{
+    /// <summary>
+    /// Example demonstrating creating a custom device code flow authentication provider and attaching it to the driver.
+    /// This is helpful for applications that wish to override the Callback for the Device Code Result implemented by the SqlClient driver.
+    /// </summary>
+    public class CustomDeviceCodeFlowAzureAuthenticationProvider : SqlAuthenticationProvider
+    {
+        public override async Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters)
+        {
+            string clientId = "my-client-id";
+            string clientName = "My Application Name";
+            string s_defaultScopeSuffix = "/.default";
+
+            string[] scopes = new string[] { parameters.Resource.EndsWith(s_defaultScopeSuffix) ? parameters.Resource : parameters.Resource + s_defaultScopeSuffix };
+
+            IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
+                .WithAuthority(parameters.Authority)
+                .WithClientName(clientName)
+                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
+                .Build();
+
+            AuthenticationResult result = await app.AcquireTokenWithDeviceCode(scopes,
+                    deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult)).ExecuteAsync();
+            return new SqlAuthenticationToken(result.AccessToken, result.ExpiresOn);
+        }
+
+        public override bool IsSupported(SqlAuthenticationMethod authenticationMethod) => authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);
+
+        private Task CustomDeviceFlowCallback(DeviceCodeResult result)
+        {
+            Console.WriteLine(result.Message);
+            return Task.FromResult(0);
+        }
+    }
+
+    public class Program
+    {
+        public static void Main()
+        {
+            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!");
+            }
+        }
+    }
+}
+//</Snippet1>

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

@@ -0,0 +1,69 @@
+<docs>
+  <members name="ActiveDirectoryAuthenticationProvider">
+    <ActiveDirectoryAuthenticationProvider>
+      <summary>
+      This class implements <see cref="T:Microsoft.Data.SqlClient.SqlAuthenticationProvider" /> and is used for active directory federated authentication mechanisms.
+      </summary>
+    </ActiveDirectoryAuthenticationProvider>
+    <ctor>
+      <summary>
+        Initializes the <see cref="T:Microsoft.Data.SqlClient.ActiveDirectoryAuthenticationProvider" /> class.
+      </summary>
+    </ctor>
+    <ctor2>
+      <param name="deviceCodeFlowCallbackMethod">The callback method to be used by driver when performing 'Active Directory Device Code Flow' authentication.</param>
+      <summary>
+        Initializes the <see cref="T:Microsoft.Data.SqlClient.ActiveDirectoryAuthenticationProvider" /> class with provided device code flow callback method.
+      </summary>
+    </ctor2>
+    <AcquireTokenAsync>
+      <param name="parameters">The Active Directory authentication parameters passed by the driver to authentication providers.</param>
+      <summary>Acquires a security token from the authority.</summary>
+      <returns>Represents an asynchronous operation that returns the AD authentication token.</returns>
+    </AcquireTokenAsync>
+    <SetDeviceCodeFlowCallback>
+      <param name="deviceCodeFlowCallbackMethod">The callback method to be used by driver when performing 'Active Directory Device Code Flow' authentication.</param>
+      <summary>Set's callback method that overrides driver's default implementation to process result  when performing 'Active Directory Device Code Flow' authentication.</summary>
+    </SetDeviceCodeFlowCallback>
+    <BeforeLoad>
+      <param name="authentication">The authentication method.</param>
+      <summary>This method is called immediately before the provider is added to SQL drivers registry. </summary>
+      <remarks>Avoid performing long-waiting tasks in this method, since it can block other threads from accessing the provider registry.</remarks>
+    </BeforeLoad>
+    <BeforeUnload>
+      <param name="authentication">The authentication method.</param>
+      <summary>This method is called immediately before the provider is removed from the SQL drivers registry. </summary>
+      <remarks>For example, this method is called when a different provider with the same authentication method overrides this provider in the SQL drivers registry. Avoid performing long-waiting task in this method, since it can block other threads from accessing the provider registry.</remarks>
+    </BeforeUnload>
+    <IsSupported>
+      <param name="authentication">The authentication method.</param>
+      <summary>Indicates whether the specified authentication method is supported.</summary>
+      <returns>
+        <see langword="true" /> if the specified authentication method is supported; otherwise, <see langword="false" />.
+      </returns>
+      <remarks>
+        <format type="text/markdown">
+          <![CDATA[  
+
+## Remarks  
+ The supported authentication methods are:
+
+|Authentication Method|
+|----------------|
+|<xref:Microsoft.Data.SqlClient.SqlAuthenticationMethod.ActiveDirectoryPassword%2A>|
+|<xref:Microsoft.Data.SqlClient.SqlAuthenticationMethod.ActiveDirectoryIntegrated%2A>|
+|<xref:Microsoft.Data.SqlClient.SqlAuthenticationMethod.ActiveDirectoryInteractive%2A>|
+|<xref:Microsoft.Data.SqlClient.SqlAuthenticationMethod.ActiveDirectoryServicePrincipal%2A>|
+|<xref:Microsoft.Data.SqlClient.SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow%2A>|
+
+## Examples  
+ The following example demonstrates providing a custom device flow callback to SqlClient driver for Device Code Flow authentication method:
+
+ [!code-csharp[ActiveDirectory_DeviceCodeFlowCallback Example#1](~/../sqlclient/doc/samples/AADAuthenticationCustomDeviceFlowCallback.cs#1)]
+
+ ]]>
+        </format>
+      </remarks>
+    </IsSupported>
+  </members>
+</docs>

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

@@ -29,5 +29,9 @@
             <summary>The authentication method uses Active Directory Service Principal. Use Active Directory Service Principal to connect to a SQL Database using the client ID and secret of a service principal identity.</summary>
             <value>5</value>
         </ActiveDirectoryServicePrincipal>
+        <ActiveDirectoryDeviceCodeFlow>
+            <summary>The authentication method uses Active Directory Device Code Flow. Use Active Directory Device Code Flow to connect to a SQL Database from devices and operating systems that do not provide a Web browser, using another device to perform interactive authentication.</summary>
+            <value>6</value>
+        </ActiveDirectoryDeviceCodeFlow>
     </members>
 </docs>

src/Microsoft.Data.SqlClient.sln

@@ -78,6 +78,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Microsoft.Data.Sql", "Micro
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Microsoft.Data.SqlClient", "Microsoft.Data.SqlClient", "{C05F4FFE-6A14-4409-AA0A-10630BE4F1EE}"
 	ProjectSection(SolutionItems) = preProject
+		..\doc\snippets\Microsoft.Data.SqlClient\ActiveDirectoryAuthenticationProvider.xml = ..\doc\snippets\Microsoft.Data.SqlClient\ActiveDirectoryAuthenticationProvider.xml
 		..\doc\snippets\Microsoft.Data.SqlClient\ApplicationIntent.xml = ..\doc\snippets\Microsoft.Data.SqlClient\ApplicationIntent.xml
 		..\doc\snippets\Microsoft.Data.SqlClient\OnChangeEventHandler.xml = ..\doc\snippets\Microsoft.Data.SqlClient\OnChangeEventHandler.xml
 		..\doc\snippets\Microsoft.Data.SqlClient\PoolBlockingPeriod.xml = ..\doc\snippets\Microsoft.Data.SqlClient\PoolBlockingPeriod.xml

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

@@ -69,6 +69,8 @@ public enum SqlAuthenticationMethod
         ActiveDirectoryPassword = 2,
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlAuthenticationMethod.xml' path='docs/members[@name="SqlAuthenticationMethod"]/ActiveDirectoryServicePrincipal/*'/>
         ActiveDirectoryServicePrincipal = 5,
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlAuthenticationMethod.xml' path='docs/members[@name="SqlAuthenticationMethod"]/ActiveDirectoryDeviceCodeFlow/*'/>
+        ActiveDirectoryDeviceCodeFlow = 6,
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlAuthenticationMethod.xml' path='docs/members[@name="SqlAuthenticationMethod"]/NotSpecified/*'/>
         NotSpecified = 0,
         /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlAuthenticationMethod.xml' path='docs/members[@name="SqlAuthenticationMethod"]/SqlPassword/*'/>

src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/Common/DbConnectionStringCommon.cs

@@ -103,10 +103,11 @@ internal static string ConvertToString(object value)
         const string ActiveDirectoryIntegratedString = "Active Directory Integrated";
         const string ActiveDirectoryInteractiveString = "Active Directory Interactive";
         const string ActiveDirectoryServicePrincipalString = "Active Directory Service Principal";
+        const string ActiveDirectoryDeviceCodeFlowString = "Active Directory Device Code Flow";
 
         internal static bool TryConvertToAuthenticationType(string value, out SqlAuthenticationMethod result)
         {
-            Debug.Assert(Enum.GetNames(typeof(SqlAuthenticationMethod)).Length == 6, "SqlAuthenticationMethod enum has changed, update needed");
+            Debug.Assert(Enum.GetNames(typeof(SqlAuthenticationMethod)).Length == 7, "SqlAuthenticationMethod enum has changed, update needed");
 
             bool isSuccess = false;
 
@@ -140,6 +141,12 @@ internal static bool TryConvertToAuthenticationType(string value, out SqlAuthent
                 result = SqlAuthenticationMethod.ActiveDirectoryServicePrincipal;
                 isSuccess = true;
             }
+            else if (StringComparer.InvariantCultureIgnoreCase.Equals(value, ActiveDirectoryDeviceCodeFlowString)
+                || StringComparer.InvariantCultureIgnoreCase.Equals(value, Convert.ToString(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow, CultureInfo.InvariantCulture)))
+            {
+                result = SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow;
+                isSuccess = true;
+            }
             else
             {
                 result = DbConnectionStringDefaults.Authentication;
@@ -486,6 +493,7 @@ internal static bool IsValidAuthenticationTypeValue(SqlAuthenticationMethod valu
                 || value == SqlAuthenticationMethod.ActiveDirectoryIntegrated
                 || value == SqlAuthenticationMethod.ActiveDirectoryInteractive
                 || value == SqlAuthenticationMethod.ActiveDirectoryServicePrincipal
+                || value == SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow
                 || value == SqlAuthenticationMethod.NotSpecified;
         }
 
@@ -505,6 +513,8 @@ internal static string AuthenticationTypeToString(SqlAuthenticationMethod value)
                     return ActiveDirectoryInteractiveString;
                 case SqlAuthenticationMethod.ActiveDirectoryServicePrincipal:
                     return ActiveDirectoryServicePrincipalString;
+                case SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow:
+                    return ActiveDirectoryDeviceCodeFlowString;
                 default:
                     return null;
             }

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

@@ -33,6 +33,7 @@ static SqlAuthenticationProviderManager()
             Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryPassword, activeDirectoryAuthProvider);
             Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, activeDirectoryAuthProvider);
             Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryServicePrincipal, activeDirectoryAuthProvider);
+            Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow, activeDirectoryAuthProvider);
         }
 
         /// <summary>
@@ -116,6 +117,8 @@ private static SqlAuthenticationMethod AuthenticationEnumFromString(string authe
                     return SqlAuthenticationMethod.ActiveDirectoryInteractive;
                 case ActiveDirectoryServicePrincipal:
                     return SqlAuthenticationMethod.ActiveDirectoryServicePrincipal;
+                case ActiveDirectoryDeviceCodeFlow:
+                    return SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow;
                 default:
                     throw SQL.UnsupportedAuthentication(authentication);
             }

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

@@ -14,6 +14,7 @@ static SqlAuthenticationProviderManager()
             Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryIntegrated, activeDirectoryAuthProvider);
             Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, activeDirectoryAuthProvider);
             Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryServicePrincipal, activeDirectoryAuthProvider);
+            Instance.SetProvider(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow, activeDirectoryAuthProvider);
         }
     }
 }

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

@@ -18,6 +18,7 @@ internal partial class SqlAuthenticationProviderManager
         private const string ActiveDirectoryIntegrated = "active directory integrated";
         private const string ActiveDirectoryInteractive = "active directory interactive";
         private const string ActiveDirectoryServicePrincipal = "active directory service principal";
+        private const string ActiveDirectoryDeviceCodeFlow = "active directory device code flow";
 
         private readonly string _typeName;
         private readonly IReadOnlyCollection<SqlAuthenticationMethod> _authenticationsWithAppSpecifiedProvider;

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

@@ -146,6 +146,11 @@ public SqlConnection(string connectionString, SqlCredential credential) : this()
                     throw SQL.SettingCredentialWithInteractiveArgument();
                 }
 
+                if (UsesActiveDirectoryDeviceCodeFlow(connectionOptions))
+                {
+                    throw SQL.SettingCredentialWithDeviceFlowArgument();
+                }
+
                 Credential = credential;
             }
             // else
@@ -401,6 +406,11 @@ private bool UsesActiveDirectoryInteractive(SqlConnectionString opt)
             return opt != null ? opt.Authentication == SqlAuthenticationMethod.ActiveDirectoryInteractive : false;
         }
 
+        private bool UsesActiveDirectoryDeviceCodeFlow(SqlConnectionString opt)
+        {
+            return opt != null ? opt.Authentication == SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow : false;
+        }
+
         private bool UsesAuthentication(SqlConnectionString opt)
         {
             return opt != null ? opt.Authentication != SqlAuthenticationMethod.NotSpecified : false;
@@ -457,7 +467,7 @@ public override string ConnectionString
                     SqlConnectionString connectionOptions = new SqlConnectionString(value);
                     if (_credential != null)
                     {
-                        // Check for Credential being used with Authentication=ActiveDirectoryIntegrated/ActiveDirectoryInteractive. Since a different error string is used
+                        // Check for Credential being used with Authentication=ActiveDirectoryIntegrated/ActiveDirectoryInteractive/ActiveDirectoryDeviceCodeFlow. Since a different error string is used
                         // for this case in ConnectionString setter vs in Credential setter, check for this error case before calling
                         // CheckAndThrowOnInvalidCombinationOfConnectionStringAndSqlCredential, which is common to both setters.
                         if (UsesActiveDirectoryIntegrated(connectionOptions))
@@ -468,6 +478,10 @@ public override string ConnectionString
                         {
                             throw SQL.SettingInteractiveWithCredential();
                         }
+                        else if (UsesActiveDirectoryDeviceCodeFlow(connectionOptions))
+                        {
+                            throw SQL.SettingDeviceFlowWithCredential();
+                        }
 
                         CheckAndThrowOnInvalidCombinationOfConnectionStringAndSqlCredential(connectionOptions);
                     }
@@ -698,6 +712,10 @@ public SqlCredential Credential
                     {
                         throw SQL.SettingCredentialWithInteractiveInvalid();
                     }
+                    else if (UsesActiveDirectoryDeviceCodeFlow((SqlConnectionString)ConnectionOptions))
+                    {
+                        throw SQL.SettingCredentialWithDeviceFlowInvalid();
+                    }
 
                     CheckAndThrowOnInvalidCombinationOfConnectionStringAndSqlCredential((SqlConnectionString)ConnectionOptions);
                     if (_accessToken != null)

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

@@ -173,9 +173,9 @@ override protected DbConnectionPoolGroupOptions CreateConnectionPoolGroupOptions
                     connectionTimeout = int.MaxValue;
                 }
 
-                if (opt.Authentication == SqlAuthenticationMethod.ActiveDirectoryInteractive)
+                if (opt.Authentication == SqlAuthenticationMethod.ActiveDirectoryInteractive || opt.Authentication == SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow)
                 {
-                    // interactive mode will always have pool's CreateTimeout = 10 x ConnectTimeout.
+                    // interactive/device code flow mode will always have pool's CreateTimeout = 10 x ConnectTimeout.
                     if (connectionTimeout >= Int32.MaxValue / 10)
                     {
                         connectionTimeout = Int32.MaxValue;
@@ -184,7 +184,7 @@ override protected DbConnectionPoolGroupOptions CreateConnectionPoolGroupOptions
                     {
                         connectionTimeout *= 10;
                     }
-                    SqlClientEventSource.Log.TraceEvent("<sc.SqlConnectionFactory.CreateConnectionPoolGroupOptions>Set connection pool CreateTimeout={0} when AD Interactive is in use.", connectionTimeout);
+                    SqlClientEventSource.Log.TraceEvent("<sc.SqlConnectionFactory.CreateConnectionPoolGroupOptions>Set connection pool CreateTimeout={0} when {1} is in use.", connectionTimeout, opt.Authentication);
                 }
                 poolingOptions = new DbConnectionPoolGroupOptions(
                                                 opt.IntegratedSecurity,