dotnet · scottaddie · Aug 27, 2025 · Aug 20, 2025 · Aug 20, 2025 · Aug 20, 2025
@@ -37,72 +37,6 @@ The following example demonstrates using an [`InteractiveBrowserCredential`](/do
 
 For more exact control, such as setting redirect URIs, you can supply specific arguments to `InteractiveBrowserCredential` such as `redirect_uri`.
 
-## Interactive brokered authentication
-
-This method interactively authenticates an application through <xref:Azure.Identity.InteractiveBrowserCredential> by collecting user credentials using the 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. Currently, only the Windows authentication broker, Web Account Manager (WAM), is supported. Users on macOS and Linux will be authenticated through the non-brokered interactive browser flow.
-
-WAM enables identity providers such as Microsoft Entra ID to natively plug into the OS and provide the service to other apps to provide a more secure login process. 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 can 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.
-
-Interactive brokered authentication enables the application for all operations allowed by the interactive login credentials. 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.
-
-### Enable applications for interactive brokered authentication
-
-Perform the following steps to enable the application to authenticate through the interactive broker flow.
-
-1. On the [Azure portal](https://portal.azure.com), navigate to **Microsoft Entra ID** and select **App registrations** on the left-hand menu.
-1. Select the registration for your app, then select **Authentication**.
-1. Add the WAM redirect URI to your app registration via a platform configuration:
-    1. Under **Platform configurations**, select **+ Add a platform**.
-    1. Under **Configure platforms**, select the tile for your application type (platform) to configure its settings, such as **mobile and desktop applications**.
-    1. In **Custom redirect URIs**, enter the following WAM redirect URI:
-
-        ```text
-        ms-appx-web://microsoft.aad.brokerplugin/{client_id}
-        ```
-
-         The `{client_id}` placeholder must be replaced with the **Application (client) ID** listed on the **Overview** pane of the app registration.
-
-    1. Select **Configure**.
-
-    To learn more, see [Add a redirect URI to an app registration](/entra/identity-platform/quickstart-register-app#add-a-redirect-uri).
-
-1. Back on the **Authentication** pane, under **Advanced settings**, select **Yes** for **Allow public client flows**.
-1. Select **Save** to apply the changes.
-1. To authorize the application for specific resources, navigate to the resource in question, select **API Permissions**, and enable **Microsoft Graph** and other resources you want to access. Microsoft Graph is usually enabled by default.
-
-    > [!IMPORTANT]
-    > You must also be the admin of your tenant to grant consent to your application when you sign in for the first time.
-
-### Example using InteractiveBrowserCredential
-
-The following example demonstrates using an <xref:Azure.Identity.InteractiveBrowserCredential> in a Windows Forms app to authenticate with the [`BlobServiceClient`](/dotnet/api/azure.storage.blobs.blobserviceclient):
-
-:::code language="csharp" source="../snippets/authentication/additional-auth/interactive/InteractiveBrokeredAuth.cs" highlight="16-20":::
-
-> [!NOTE]
-> Visit the [Parent window handles](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam#parent-window-handles) and [Retrieve a window handle](/windows/apps/develop/ui-input/retrieve-hwnd) articles for more information about retrieving window handles.
-
-For the code to run successfully, your user account must be assigned an Azure role on the storage account that allows access to blob containers such as **Storage Account Data Contributor**. If an app is specified, it must have API permissions set for **user_impersonation Access Azure Storage** (step 6 in the previous section). This API permission allows the app to access Azure storage on behalf of the signed-in user after consent is granted during sign-in.
-
-The following screenshot shows the user sign-in experience:
-
-:::image type="content" source="../media/web-account-manager-sign-in-account-picker.png" alt-text="A screenshot that shows the sign-in experience when using the interactive browser broker credential to authenticate a user." :::
-
-### Authenticate the default system account via WAM
-
-Many people always sign in to Windows with the same user account and, therefore, only ever want to authenticate using that account. WAM and `InteractiveBrowserCredential` also support a silent login process that automatically uses a default account so the user doesn't have to repeatedly select it.
-
-The following example shows how to enable sign-in with the default system account:
-
-:::code language="csharp" source="../snippets/authentication/additional-auth/interactive/SilentBrokeredAuth.cs" highlight="16-24":::
-
-Once you opt in to this behavior, the credential attempts to sign in by asking the underlying Microsoft Authentication Library (MSAL) to perform the sign-in for the default system account. If the sign-in fails, the credential falls back to displaying the account picker dialog, from which the user can select the appropriate account.
-
 ## Device code authentication
 
 This method interactively authenticates a user on devices with limited UI (typically devices without a keyboard):

@@ -0,0 +1,125 @@
+---
+title: Authenticate .NET apps to Azure using brokered authentication.
+description: Learn how to authenticate your app to Azure services when using the Azure SDK for .NET during local development using brokered authentication.
+ms.topic: how-to
+ms.custom: devx-track-dotnet, engagement-fy23, devx-track-azurecli
+ms.date: 08/20/2025
+zone_pivot_groups: operating-systems-set-one
+---
+
+# Authenticate .NET apps to Azure services during local development using interactive brokered authentication
+
+Interactive brokered authentication collects user credentials using the system authentication broker to authenticate an app with <xref:Azure.Identity.InteractiveBrowserCredential>. 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.
+
+Interactive brokered authentication offers the following benefits:
+
+- **Enables Single Sign-On (SSO):** Enables apps to simplify how users authenticate with Microsoft Entra ID and protects Microsoft Entra ID refresh tokens from exfiltration and misuse.
+- **Enhanced security.** Many security enhancements are delivered with the broker, without needing to update the app logic.
+- **Feature support.** With the help of the broker developers can access rich OS and service capabilities.
+- **System integration.** Applications that use the broker plug-and-play with the built-in account picker, allowing the user to quickly pick an existing account instead of reentering the same credentials over and over.
+- **Token Protection.** Ensures that the refresh tokens are device bound and enables apps to acquire device bound access tokens. See [Token Protection](/azure/active-directory/conditional-access/concept-token-protection).
+
+:::zone target="docs" pivot="os-windows"
+
+Windows provides an authentication broker called [Web Account Manager (WAM)](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam). Wam enables identity providers such as Microsoft Entra ID to natively plug into the OS and provide the service to other apps for a more secure login process. Brokered authentication enables the app for all operations allowed by the interactive login credentials.
+
+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.
+
+:::zone-end
+
+:::zone target="docs" pivot="os-macos"
+
+Authentication brokers aren't preinstalled on macOS, but they are available through apps developed by Microsoft, such as Company Portal. These apps are installed when a macOS device is enrolled in a company device fleet via a solution like Microsoft Intune. To learn more about Apple device set up with the Microsoft Identity Platform, refer to [Microsoft Enterprise SSO plug-in for Apple devices](/entra/identity-platform/apple-sso-plugin).
+
+:::zone-end
+
+:::zone target="docs" pivot="os-linux"
+
+The Linux operating system uses [Microsoft single sign-on for Linux](/entra/identity/devices/sso-linux) as its authentication broker.
+
+> [!NOTE]
+> Microsoft SSO for Linux authentication broker support is introduced with `Azure.Identity.Broker` version v1.3.0.
+
+:::zone-end
+
+## Configure the app for brokered authentication
+
+Complete the following steps to enable the application to authenticate through the broker flow:
+
+1. In the [Azure portal](https://portal.azure.com), navigate to **Microsoft Entra ID** and select **App registrations** on the left-hand menu.
+1. Select the registration for your app, then select **Authentication**.
+1. Add the redirect URI to your app registration via a platform configuration:
+    1. Under **Platform configurations**, select **+ Add a platform**.
+    1. Under **Configure platforms**, select the tile for your application type (platform) to configure its settings, such as **mobile and desktop applications**.
+    1. In **Custom redirect URIs**, enter the following redirect URI for your platform:
+
+        | Platform    | Redirect URI                                                                                                          |
+        |-------------|-----------------------------------------------------------------------------------------------------------------------|
+        | Windows 10+ | `ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id`                                                             |
+        | macOS       | `msauth.com.msauth.unsignedapp://auth` for unsigned apps `msauth.BUNDLE_ID://auth` for signed apps                    |
+        | WSL         | `ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id`                                                             |
+        | Linux       | `https://login.microsoftonline.com/common/oauth2/nativeclient`                                                        |
+
+         The `{your_client_id}` or `{BUNDLE_ID}` placeholder must be replaced with the **Application (client) ID** listed on the **Overview** pane of the app registration.
+
+    1. Select **Configure**.
+
+    To learn more, see [Add a redirect URI to an app registration](/entra/identity-platform/quickstart-register-app#add-a-redirect-uri).
+
+1. Back on the **Authentication** pane, under **Advanced settings**, select **Yes** for **Allow public client flows**.
+1. Select **Save** to apply the changes.
+1. To authorize the application for specific resources, navigate to the resource in question, select **API Permissions**, and enable **Microsoft Graph** and other resources you want to access.
+
+    > [!IMPORTANT]
+    > You must also be the admin of your tenant to grant consent to your application when you sign in for the first time.
+
+### Assign roles
+
+For your app code to run successfully with brokered auth, you need grant your user account permissions through [Azure role-based access control (RBAC)](/azure/role-based-access-control/overview). Your user account must be [assigned an appropriate role](/dotnet/azure/sdk/authentication/local-development-dev-accounts) on the corresponding Azure service. For example:
+
+- **Azure Blob Storage**: Assign a role such as **Storage Account Data Contributor**.
+- **Azure Key Vault**: Assign a role such as **Key Vault Secrets Officer**.
+
+If an app is specified, it must have API permissions set for **user_impersonation Access Azure Storage** (step 6 in the previous section). This API permission allows the app to access Azure storage on behalf of the signed-in user after consent is granted during sign-in.
+
+## Implement the code
+
+Complete the following steps to use <xref:Azure.Identity.InteractiveBrowserCredential> in a MAUI app to authenticate with the [`SecretClient`](/dotnet/api/azure.security.keyvault.secrets.secretclient):
+
+1. Install the [Azure.Identity](https://www.nuget.org/packages/Azure.Identity) and [Azure.Identity.Broker](https://www.nuget.org/packages/Azure.Identity.Broker) packages.
+
+    > [!NOTE]
+    > macOS and Linux support exists in `Azure.Identity.Broker` versions 1.3.0 and later.
+
+1. Get a reference to the parent window on top of which the account picker dialog should appear.
+1. Create an instance of <xref:Azure.Identity.InteractiveBrowserCredential> that accepts an instance of <xref:Azure.Identity.Broker.InteractiveBrowserCredentialBrokerOptions>.
+
+:::zone target="docs" pivot="os-windows"
+
+:::code language="csharp" source="../snippets/authentication/brokered/maui-app/MainPage.xaml.cs" highlight="37-49" :::
+
+The following screenshot shows the user sign-in experience:
+
+:::image type="content" source="../media/web-account-manager-sign-in-account-picker.png" alt-text="A screenshot that shows the sign-in experience when using a broker-enabled InteractiveBrowserCredential instance to authenticate a user." :::
+
+:::zone-end
+
+:::zone target="docs" pivot="os-macos"
+
+:::code language="csharp" source="../snippets/authentication/brokered/maui-app/MainPage.xaml.cs" highlight="53-65" :::
+
+:::zone-end
+
+:::zone target="docs" pivot="os-linux"
+
+:::code language="csharp" source="../snippets/authentication/brokered/console-app/Program.cs" highlight="22-28" :::
+
+:::zone-end
+
+### Authenticate the default system account
+
+`InteractiveBrowserCredential` also supports a silent sign-in process that automatically uses a default account so the user doesn't have to repeatedly select it. Once you opt-in to this behavior, the credential attempts to sign-in by asking the underlying Microsoft Authentication Library (MSAL) to perform the sign-in for the default system account. If the sign-in fails, the credential falls back to displaying the account picker dialog, from which the user can select the appropriate account.
+
+The previous example shows how to enable sign-in with the default system account:
+
+:::code language="csharp" source="../snippets/authentication/brokered/console-app/Program.cs" range="22-28" highlight="3" :::
@@ -15,5 +15,7 @@
     <!-- ASP.NET Core packages -->
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="8.0.8" />
     <PackageVersion Include="Swashbuckle.AspNetCore" Version="6.7.3" />
+  <PackageVersion Include="Microsoft.Maui.Controls" Version="9.0.0" />
+  <PackageVersion Include="Microsoft.Extensions.Logging.Debug" Version="9.0.0" />
   </ItemGroup>
 </Project>
@@ -20,12 +20,12 @@ private void testInteractiveBrokeredAuth_Click(object sender, EventArgs e)
                 new InteractiveBrowserCredentialBrokerOptions(windowHandle));
 
             // To authenticate and authorize with an Entra ID app registration, substitute the
-            // <app_id> and <tenant_id> placeholders with the values for your app and tenant.
+            // <your-tenant-id> and <your-client-id> placeholders with the values for your app and tenant.
             // var credential = new InteractiveBrowserCredential(
             //    new InteractiveBrowserCredentialBrokerOptions(windowHandle)
             //        { 
-            //            TenantId = "your-tenant-id",
-            //            ClientId = "your-client-id"
+            //            TenantId = "<your-tenant-id>",
+            //            ClientId = "<your-client-id>"
             //        }
             // );
 

@@ -24,12 +24,12 @@ private void testSilentBrokeredAuth_Click(object sender, EventArgs e)
                 });
 
             // To authenticate and authorize with an app, substitute the
-            // <app_id> and <tenant_id> placeholders with the values for your app and tenant.
+            // <your-tenant-id> and <your-client-id> placeholders with the values for your app and tenant.
             // var credential = new InteractiveBrowserCredential(
             //    new InteractiveBrowserCredentialBrokerOptions(windowHandle)
             //        { 
-            //            TenantId = "your-tenant-id",
-            //            ClientId = "your-client-id"
+            //            TenantId = "<your-tenant-id>",
+            //            ClientId = "<your-client-id>"
             //        }
             // );
 

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ProjectUISubcaption>Linux</ProjectUISubcaption>
+  </PropertyGroup>
+  <ItemGroup>
+  <PackageReference Include="Azure.Identity" />
+  <PackageReference Include="Azure.Identity.Broker" />
+  <PackageReference Include="Azure.Security.KeyVault.Secrets" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,53 @@
+using System;
+using System.Runtime.InteropServices;
+using Azure;
+using Azure.Identity;
+using Azure.Identity.Broker;
+using Azure.Security.KeyVault.Secrets;
+
+/// <summary>
+/// Get the handle of the console window for Linux
+/// </summary>
+[DllImport("libX11")]
+static extern IntPtr XOpenDisplay(string display);
+
+[DllImport("libX11")]
+static extern IntPtr XRootWindow(IntPtr display, int screen);
+
+try
+{
+    IntPtr parentWindowHandle = XRootWindow(XOpenDisplay(null), 0);
+    Func<IntPtr> consoleWindowHandleProvider = () => parentWindowHandle;
+
+    InteractiveBrowserCredentialBrokerOptions brokerOptions = new(parentWindowHandle)
+    {
+        UseDefaultBrokerAccount = true,
+    };
+
+    // Create the InteractiveBrowserCredential using broker support
+    InteractiveBrowserCredential credential = new(brokerOptions);
+
+    Uri vaultUri = new("https://<your-key-vault-name>.vault.azure.net/");
+    SecretClient client = new(vaultUri, credential);
+
+    Console.WriteLine("Retrieving secret 'MySecret' from Key Vault...");
+    KeyVaultSecret secret = await client.GetSecretAsync("MySecret");
+    Console.WriteLine($"Secret value: {secret.Value}");
+
+    return 0;
+}
+catch (AuthenticationFailedException ex)
+{
+    Console.Error.WriteLine($"Authentication failed: {ex.Message}");
+    return 2;
+}
+catch (RequestFailedException ex)
+{
+    Console.Error.WriteLine($"Key Vault request failed: {ex.Message}");
+    return 3;
+}
+catch (Exception ex)
+{
+    Console.Error.WriteLine($"Unexpected error: {ex.Message}");
+    return 1;
+}
@@ -0,0 +1,14 @@
+<?xml version = "1.0" encoding = "UTF-8" ?>
+<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+             xmlns:local="clr-namespace:SecretVaultApp"
+             x:Class="SecretVaultApp.App">
+    <Application.Resources>
+        <ResourceDictionary>
+            <ResourceDictionary.MergedDictionaries>
+                <ResourceDictionary Source="resources/Styles/Colors.xaml" />
+                <ResourceDictionary Source="resources/Styles/Styles.xaml" />
+            </ResourceDictionary.MergedDictionaries>
+        </ResourceDictionary>
+    </Application.Resources>
+</Application>
@@ -0,0 +1,14 @@
+namespace SecretVaultApp;
+
+public partial class App : Application
+{
+	public App()
+	{
+		InitializeComponent();
+	}
+
+	protected override Window CreateWindow(IActivationState? activationState)
+	{
+		return new Window(new AppShell());
+	}
+}