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

@@ -30,6 +30,24 @@ public sealed partial class SqlNotificationRequest
 }
 namespace Microsoft.Data.SqlClient
 {
+    /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/ActiveDirectoryAuthenticationProvider/*'/>
+    public sealed class ActiveDirectoryAuthenticationProvider : SqlAuthenticationProvider
+    {
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/ctor/*'/>
+        public ActiveDirectoryAuthenticationProvider() { }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/ctor2/*'/>
+        public ActiveDirectoryAuthenticationProvider(System.Func<Microsoft.Identity.Client.DeviceCodeResult, System.Threading.Tasks.Task> deviceCodeFlowCallbackMethod) { }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/AcquireTokenAsync/*'/>
+        public override System.Threading.Tasks.Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters) { throw null; }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/SetDeviceCodeFlowCallback/*'/>
+        public void SetDeviceCodeFlowCallback(System.Func<Microsoft.Identity.Client.DeviceCodeResult, System.Threading.Tasks.Task> deviceCodeFlowCallbackMethod) { }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/IsSupported/*'/>
+        public override bool IsSupported(SqlAuthenticationMethod authentication) { throw null; }
+        /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/BeforeLoad/*'/>
+        public override void BeforeLoad(SqlAuthenticationMethod authentication) { }
+        /// <include file='../../../..//doc/snippets/Microsoft.Data.SqlClient/ActiveDirectoryAuthenticationProvider.xml' path='docs/members[@name="ActiveDirectoryAuthenticationProvider"]/BeforeUnload/*'/>
+        public override void BeforeUnload(SqlAuthenticationMethod authentication) { }
+    }
     /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/ApplicationIntent.xml' path='docs/members[@name="ApplicationIntent"]/ApplicationIntent/*'/>
     public enum ApplicationIntent
     {
@@ -69,6 +87,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/ref/Microsoft.Data.SqlClient.csproj

@@ -19,4 +19,7 @@
     <Compile Include="Microsoft.Data.SqlClient.NetCoreApp.cs" />
     <PackageReference Include="System.Security.Cryptography.Cng" Version="$(SystemSecurityCryptographyCngVersion)" />
   </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Identity.Client" Version="$(MicrosoftIdentityClientVersion)" />
+  </ItemGroup>
 </Project>

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;