Extracted broker auth into new doc #48046
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| 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 | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
| - **Enhanced 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 secure login services to apps. Brokered authentication enables the app for all operations allowed by the interactive login credentials. | ||
|
|
||
| Personal Microsoft accounts and work or school accounts are supported. On supported Windows versions, the default browser-based UI is replaced with a smoother authentication experience, similar to built-in Windows apps. | ||
|
|
||
| :::zone-end | ||
|
|
||
| :::zone target="docs" pivot="os-macos" | ||
|
|
||
| macOS doesn't natively include a built-in authentication broker. Brokered authentication is supported via the `Azure.Identity.Broker` library, which uses platform-specific mechanisms and may integrate with apps like Microsoft Company Portal when devices are managed. For more information, see [Microsoft Enterprise SSO plug-in for Apple devices](/entra/identity-platform/apple-sso-plugin). | ||
|
|
||
| :::zone-end | ||
|
|
||
| :::zone target="docs" pivot="os-linux" | ||
|
|
||
| Linux uses [Microsoft single sign-on for Linux](/entra/identity/devices/sso-linux) as its authentication broker. | ||
|
|
||
| :::zone-end | ||
|
|
||
| ## Configure the app for brokered authentication | ||
|
|
||
| To enable brokered authentication in your application, follow these steps: | ||
|
|
||
| 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 appropriate 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+ or WSL | `ms-appx-web://Microsoft.AAD.BrokerPlugin/{your_client_id}` | | ||
| | macOS | `msauth.com.msauth.unsignedapp://auth` for unsigned apps<br>`msauth.{bundle_id}://auth` for signed apps | | ||
|
Check failure on line 56 in docs/azure/sdk/authentication/local-development-broker.md
|
||
| | | ||
alexwolfmsft marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| | Linux | `https://login.microsoftonline.com/common/oauth2/nativeclient` | | ||
alexwolfmsft marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Replace `{your_client_id}` or `{bundle_id}` with the **Application (client) ID** from the app registration's **Overview** pane. | ||
|
Check failure on line 60 in docs/azure/sdk/authentication/local-development-broker.md
|
||
|
|
||
| 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 | ||
alexwolfmsft marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| To run your app code successfully with brokered authentication, grant your user account permissions using [Azure role-based access control (RBAC)](/azure/role-based-access-control/overview). Assign an appropriate role to your user account for the relevant Azure service. For example: | ||
|
|
||
| - **Azure Blob Storage**: Assign the **Storage Account Data Contributor** role. | ||
| - **Azure Key Vault**: Assign the **Key Vault Secrets Officer** role. | ||
|
|
||
| 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 | ||
|
|
||
| :::zone target="docs" pivot="os-windows, os-macos" | ||
|
|
||
| The Azure Identity library supports brokered authentication using <xref:Azure.Identity.InteractiveBrowserCredential>. For example, to use `InteractiveBrowserCredential` in a MAUI app to authenticate to Azure Key Vault with the [`SecretClient`](/dotnet/api/azure.security.keyvault.secrets.secretclient), follow these steps: | ||
|
|
||
| :::zone-end | ||
|
|
||
| :::zone target="docs" pivot="os-linux" | ||
|
|
||
| .NET and the `Azure.Identity` libraries provide interactive brokered authentication using <xref:Azure.Identity.InteractiveBrowserCredential>. For example, to use `InteractiveBrowserCredential` in a console app to authenticate to Azure Key Vault with the [`SecretClient`](/dotnet/api/azure.security.keyvault.secrets.secretclient), follow these steps: | ||
|
|
||
alexwolfmsft marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| :::zone-end | ||
|
|
||
| 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] | ||
alexwolfmsft marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > macOS and Linux support exists in `Azure.Identity.Broker` versions 1.3.0 and later. | ||
alexwolfmsft marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| 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> using <xref:Azure.Identity.Broker.InteractiveBrowserCredentialBrokerOptions>. | ||
|
|
||
| :::zone target="docs" pivot="os-windows" | ||
|
|
||
| :::code language="csharp" source="../snippets/authentication/brokered/maui-app/MainPage.xaml.cs" id="snippet_brokered_windows" highlight="6-13"::: | ||
|
|
||
| :::zone-end | ||
|
|
||
| :::zone target="docs" pivot="os-macos" | ||
|
|
||
| :::code language="csharp" source="../snippets/authentication/brokered/maui-app/MainPage.xaml.cs" id="snippet_brokered_macos" highlight="6-13"::: | ||
|
|
||
| :::zone-end | ||
|
|
||
| :::zone target="docs" pivot="os-linux" | ||
|
|
||
| :::code language="csharp" source="../snippets/authentication/brokered/console-app/Program.cs" id="snippet_brokered_linux" highlight="15-21"::: | ||
|
|
||
| :::zone-end | ||
|
|
||
| In the preceding example, property <xref:Azure.Identity.Broker.InteractiveBrowserCredentialBrokerOptions.UseDefaultBrokerAccount%2A> is set to `true`, which opts into a silent, brokered authentication flow with the default system account. In this way, the user doesn't have to repeatedly select the same account. If silent, brokered authentication fails, or `UseDefaultBrokerAccount` is set to `false`, `InteractiveBrowserCredential` falls back to interactive, brokered authentication. | ||
|
|
||
| :::zone target="docs" pivot="os-windows" | ||
|
|
||
| The following screenshot shows the alternative interactive brokered authentication experience: | ||
alexwolfmsft marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| :::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-linux" | ||
|
|
||
| The following video shows the alternative interactive brokered authentication experience: | ||
alexwolfmsft marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| :::image type="content" source="../media/linux-entra-login.gif" alt-text="An animated gif that shows the sign-in experience when using a broker-enabled InteractiveBrowserCredential instance to authenticate a user." ::: | ||
|
|
||
| :::zone-end | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| using System; | ||
| using System.Runtime.InteropServices; | ||
| using Azure; | ||
| using Azure.Identity; | ||
| using Azure.Identity.Broker; | ||
| using Azure.Security.KeyVault.Secrets; | ||
|
|
||
| #region snippet_brokered_linux | ||
| /// <summary> | ||
alexwolfmsft marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| /// 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 options = new(parentWindowHandle) | ||
| { | ||
| UseDefaultBrokerAccount = true, | ||
| }; | ||
|
|
||
| // Create the InteractiveBrowserCredential using broker support | ||
| InteractiveBrowserCredential credential = new(options); | ||
|
|
||
| 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"); | ||
|
|
||
| return 0; | ||
| } | ||
| #endregion | ||
| 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; | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.