Wham! Authentication broker support lands in the Azure Identity libraries.

Scott Addie

Xiang Yan

In the November release of the Azure Identity client libraries, system authentication broker support reached stable form. Extension packages were created to enable this interactive authentication feature, as displayed in the following table.

For now, this feature is limited to Windows users only. At the time of writing, the team is designing macOS broker support; Linux support follows that release.

What is a system authentication broker?

A system authentication broker is an app running on a user’s machine that manages the authentication handshakes and token maintenance for all connected accounts. On Windows, the authentication broker is Web Account Manager (WAM). WAM made its debut in Windows 10 and Windows Server 2019 and continues to ship in the latest releases of Windows. Open the Services snap-in control file via services.msc, and you see WAM listed:

WAM is a broker service that allows apps to request OAuth tokens from identity providers, such as Microsoft Entra ID, in a seamless fashion. With it, identity providers can natively plug into the OS and provide the service to other apps. In no particular order, WAM offers the following benefits:

• Feature support. Apps can access OS-level and service-level capabilities, including Windows Hello, conditional access policies, and FIDO keys.
• Streamlined single sign-on. Apps use the built-in account picker, allowing the user to select an existing account instead of repeatedly entering the same credentials.
• Enhanced security. Bug fixes and enhancements ship with Windows.
• Token protection. Refresh tokens are device-bound, and apps can acquire device-bound access tokens.

Many of Microsoft’s developer tools, including Visual Studio, Azure CLI, and Azure PowerShell, already provide WAM integration.

Interactive, brokered authentication in the Azure Identity libraries

The Azure Identity libraries’ InteractiveBrowserCredential type was extended to support WAM. Personal Microsoft accounts and work or school accounts are supported. If a supported version of Windows is used, the default browser-based UI is replaced with a smoother authentication experience, similar to Windows built-in apps.

What does the aforementioned default browser-based UI look like? On Windows, there are a couple possibilities:

1. Embedded view: A web browser hosted in a UI control. For example, a Microsoft Edge WebView2 control used in a WinForms app.
   
2. System browser: The web browser designated as the system’s default choice—Microsoft Edge in the following screenshot.
   

On macOS, Linux, and earlier versions of Windows—systems on which WAM isn’t supported—the Azure Identity libraries default to a browser-based authentication experience.

Get started

To use WAM in your app, complete these steps:

1. Add the following WAM redirect URI within your Microsoft Entra app registration in the Azure portal:

   ms-appx-web://microsoft.aad.brokerplugin/{client_id}

   The {client_id} placeholder must be replaced with the Application (client) ID listed on the Overview blade of the app registration.

2. Install the Azure Identity and Azure Identity Broker packages.
   • .NET:

     dotnet add package Azure.Identity
     dotnet add package Azure.Identity.Broker

   • Java: Include the BOM file or Include the direct dependency
   • JavaScript:

     npm install --save @azure/identity @azure/identity-broker

   • Python:

     pip install azure-identity azure-identity-broker

3. Create a broker-enabled instance of InteractiveBrowserCredential in your app. The credential requires the handle of the parent window that’s requesting the authentication flow. On Windows, the handle is an integer value that uniquely identifies the window.
   • .NET:

     using Azure.Identity;
     using Azure.Identity.Broker;
     
     // code omitted for brevity
     
     IntPtr windowHandle = GetForegroundWindow();
     InteractiveBrowserCredential credential = new(
         new InteractiveBrowserCredentialBrokerOptions(windowHandle)
     );

   • Java:

     import com.azure.identity.InteractiveBrowserCredential;
     import com.azure.identity.broker.InteractiveBrowserBrokerCredentialBuilder;
     
     // code omitted for brevity
     
     long windowHandle = getWindowHandle();
     InteractiveBrowserCredential credential = 
         new InteractiveBrowserBrokerCredentialBuilder()
             .setWindowHandle(windowHandle)
             .build();

   • JavaScript:

     import { nativeBrokerPlugin } from "@azure/identity-broker";
     import { 
       useIdentityPlugin,
       InteractiveBrowserCredential,
     } from "@azure/identity";
     
     useIdentityPlugin(nativeBrokerPlugin);
     
     // code omitted for brevity
     
     let windowHandle = getWindowHandle();
     
     const credential = new InteractiveBrowserCredential({
       brokerOptions: {
         enabled: true,
         parentWindowHandle: windowHandle,
       },
     });

   • Python:

     import win32gui
     from azure.identity.broker import InteractiveBrowserBrokerCredential
     
     # code omitted for brevity
     
     window_handle = win32gui.GetForegroundWindow()
     
     credential = InteractiveBrowserBrokerCredential(
         parent_window_handle=window_handle
     )

4. Use the broker-enabled InteractiveBrowserCredential instance.

A .NET developer’s end-to-end experience

As a .NET developer, imagine a scenario in which you created a desktop app using WinForms and C#. In that app, you use an Azure Monitor Query client library to query a Log Analytics workspace. The LogsQueryClient object in the Monitor Query library requires authentication of a work or school account to Microsoft Entra ID. You’d complete the following steps to use and test WAM:

1. Install the following NuGet packages:

   <ItemGroup>
     <PackageReference Include="Azure.Identity" Version="1.10.4" />
     <PackageReference Include="Azure.Identity.Broker" Version="1.0.0" />
     <PackageReference Include="Azure.Monitor.Query" Version="1.2.0" />
   </ItemGroup>

2. Get the handle of the parent window to which the WAM account picker window should be docked:

   private async void testBrokeredAuth_Click(object sender, EventArgs e)
   {
       IntPtr windowHandle = this.Handle;
   
       // code omitted for brevity
   }

   NOTE: To obtain a window handle for other .NET app models, such as WPF and console apps, see Parent window handles.

3. Create an instance of InteractiveBrowserCredential that accepts InteractiveBrowserCredentialBrokerOptions, passing in a window handle pointer:

   using Azure.Identity;
   using Azure.Identity.Broker;
   
   // code omitted for brevity
   
   InteractiveBrowserCredential credential;
   
   if (windowHandle != IntPtr.Zero)
   {
       credential = new(
           new InteractiveBrowserCredentialBrokerOptions(windowHandle)
       );
   }

4. Pass the InteractiveBrowserCredential instance to the Azure SDK library’s client. In this example, the Azure Monitor Query library’s LogsQueryClient is used:

   // code omitted for brevity
   
   LogsQueryClient client = new(credential);
   
   Response<LogsQueryResult> response = await client.QueryResourceAsync(
       new ResourceIdentifier(resourceId), query, QueryTimeRange.All);

   When this final line of code executes, an account picker window appears:

   Behind the scenes, the Microsoft Entra token broker plugin, represented by the Microsoft.AAD.BrokerPlugin.exe background process, facilitates authentication on behalf of the WinForms app.

   

Feedback

We value your feedback on this new feature. How can we improve upon the existing authentication broker support in the Azure Identity client libraries? Let’s have those conversations on GitHub at these locations:

• .NET
• Java
• JavaScript
• Python

Ecosystem-specific source code can be found on GitHub at the following locations:

• .NET
• Java
• JavaScript
• Python

Scott Addie Principal Product Manager, Azure SDK

Follow

Xiang Yan Senior Software Engineer, Azure SDK

Follow