dotnet · alexwolfmsft · Aug 29, 2025 · Aug 29, 2025 · Aug 29, 2025 · Aug 29, 2025
@@ -32,7 +32,7 @@ Use of connection strings should be limited to scenarios where token-based authe
 
 The specific type of token-based authentication an app should use to authenticate to Azure resources depends on where the app runs. The following diagram provides guidance for different scenarios and environments:
 
-:::image type="content" source="../media/dotnet-sdk-auth-strategy.png" alt-text="A diagram showing the recommended token-based authentication strategies for an app depending on where it's running." :::
+:::image type="content" source="../media/mermaidjs/authentication-environments.svg" alt-text="A diagram showing the recommended token-based authentication strategies for an app depending on where it's running." :::
 
 When an app is:
 
@@ -69,6 +69,13 @@ You can use your own Azure credentials to authenticate to Azure resources during
 > [!div class="nextstepaction"]
 > [Authenticate locally using developer credentials](local-development-dev-accounts.md)
 
+#### Use a broker
+
+Brokered authentication collects user credentials using the system authentication broker to authenticate an app. A system authentication broker runs on a user's machine and manages the authentication handshakes and token maintenance for all connected accounts.
+
+> [!div class="nextstepaction"]
+> [Authenticate locally using a broker](local-development-broker.md)
+
 #### Use a service principal
 
 A service principal is created in a Microsoft Entra tenant to represent an app and be used to authenticate to Azure resources. You can configure your app to use service principal credentials during local development. This method is more secure than using developer credentials and is closer to how your app will authenticate in production. However, it's still less ideal than using a managed identity due to the need for secrets.

@@ -19,6 +19,8 @@ Brokered authentication offers the following benefits:
 - **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).
 
+:::image type="content" source="../media/mermaidjs/local-broker-authentication.svg" alt-text="A diagram showing how a local .NET app uses brokered credentials to connect to Azure resources.":::
+
 :::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.

@@ -19,14 +19,15 @@ During local development, applications need to authenticate to Azure to access v
 - How to sign-in to supported local development tools
 - How to authenticate using a developer account from your app code
 
-:::image type="content" source="../media/local-dev-dev-accounts-overview.png" alt-text="A diagram showing an app running in local development using a developer tool identity to connect to Azure resources.":::
+:::image type="content" source="../media/mermaidjs/local-developer-authentication.svg" alt-text="A diagram showing an app running in local development using a developer tool identity to connect to Azure resources.":::
 
 For an app to authenticate to Azure during local development using the developer's Azure credentials, the developer must be signed-in to Azure from one of the following developer tools:
 
 - Azure CLI
 - Azure Developer CLI
 - Azure PowerShell
 - Visual Studio
+- Visual Studio Code
 
 The Azure Identity library can detect that the developer is signed-in from one of these tools. The library can then obtain the Microsoft Entra access token via the tool to authenticate the app to Azure as the signed-in user.
 

@@ -21,7 +21,7 @@ During local development, applications need to authenticate to Azure to access v
 
 Using dedicated application service principals allows you to adhere to the principle of least privilege when accessing Azure resources. Permissions are limited to the specific requirements of the app during development, preventing accidental access to Azure resources intended for other apps or services. This approach also helps avoid issues when the app is moved to production by ensuring it isn't over-privileged in the development environment.
 
-:::image type="content" source="../media/local-dev-service-principal-overview.png" alt-text="A diagram showing how a local .NET app uses the developer's credentials to connect to Azure by using locally installed development tools.":::
+:::image type="content" source="../media/mermaidjs/local-service-principal-authentication.svg" alt-text="A diagram showing how a local .NET app uses a service principal to connect to Azure resources.":::
 
 When the app is registered in Azure, an application service principal is created. For local development:
 

@@ -0,0 +1,47 @@
+---
+ms.topic: include
+ms.date: 08/07/2024
+---
+
+```mermaid
+%% STEPS TO GENERATE IMAGE 
+%% ======================= 
+%% 1. Install mermaid CLI v10.9.1 (see https://github.com/mermaid-js/mermaid-cli/blob/master/README.md): 
+%%    npm i -g @mermaid-js/mermaid-cli@10.9.1 
+%% 2. Run command: mmdc -i authentication-environments.md -o ../../media/mermaidjs/authentication-environments.svg 
+
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor': '#fff', 'edgeLabelBackground':'#fff', 'fontSize': '24px'}}}%%
+flowchart LR
+    NetApp[".NET app"]
+    Q1{Where is the app running?}
+
+    NetApp --> Q1
+
+    %% Local Development Machine Branch
+    Q1 --> LocalDev[Development machine]
+    LocalDev --> AppSP["**Service principal**"]
+    LocalDev --> DevAccount["**Developer account**"]
+    LocalDev --> Broker["**Broker**"]
+
+    %% Azure Branch
+    Q1 --> AzureApp[Azure]
+    AzureApp --> ManagedId["**Managed identity**"]
+
+    %% On-premises Server Branch
+    Q1 --> OnPremApp[On-premises server]
+    OnPremApp --> ServicePrincipal["**Service principal**"]
+
+    %% Styling
+    classDef questionBox fill:#4472C4,stroke:#333,stroke-width:2px,color:#fff,font-size:24px
+    classDef authMethod fill:#e6f2ff,stroke:#4472C4,stroke-width:2px,color:#000,font-size:24px
+    classDef envNode fill:#8fbc8f,stroke:#333,stroke-width:2px,color:#000,font-size:24px
+    classDef startNode fill:#2d5f3f,stroke:#333,stroke-width:2px,color:#fff,font-size:24px
+
+    %% Edge label styling
+    linkStyle default font-size:24px
+
+    class NetApp startNode
+    class Q1 questionBox
+    class AppSP,DevAccount,Broker,ManagedId,ServicePrincipal authMethod
+    class LocalDev,AzureApp,OnPremApp envNode
+```
@@ -0,0 +1,28 @@
+---
+ms.topic: include
+ms.date: 08/07/2024
+---
+
+```mermaid
+%% STEPS TO GENERATE IMAGE 
+%% ======================= 
+%% 1. Install mermaid CLI v10.9.1 (see https://github.com/mermaid-js/mermaid-cli/blob/master/README.md): 
+%%    npm i -g @mermaid-js/mermaid-cli@10.9.1 
+%% 2. Run command: mmdc -i local-broker-authentication.md -o ../../media/mermaidjs/local-broker-authentication.svg 
+
+flowchart LR
+    APP["Local .NET app"]
+    BK["User credentials supplied by broker"]
+    AS["Azure services"]
+
+    APP --> BK
+    BK --> AS
+
+    classDef app fill:#e6f3ff,stroke:#0078d4,stroke-width:2px,color:#000,font-size:16px
+    classDef serviceP fill:#D4F4D4,stroke:#7BC97B,stroke-width:2px,color:#000,font-size:16px
+    classDef services fill:#0078d4,stroke:#005ba1,stroke-width:2px,color:#fff,font-size:16px
+
+    class APP app
+    class SP serviceP
+    class AS services
+```
@@ -0,0 +1,49 @@
+---
+ms.topic: include
+ms.date: 08/07/2024
+---
+
+```mermaid
+%% STEPS TO GENERATE IMAGE 
+%% ======================= 
+%% 1. Install mermaid CLI v10.9.1 (see https://github.com/mermaid-js/mermaid-cli/blob/master/README.md): 
+%%    npm i -g @mermaid-js/mermaid-cli@10.9.1 
+%% 2. Run command: mmdc -i local-developer-authentication.md -o ../../media/mermaidjs/local-developer-authentication.svg 
+
+flowchart TD
+    ARL[Local .NET app]
+    
+    VS[Visual Studio]
+    VSC[Visual Studio Code]
+    AZCLI[Azure CLI]
+    AZPS[Azure PowerShell]
+    AZD[Azure Developer CLI]
+
+    DevAccount["Developer account credentials"]
+
+    AS["Azure services"]
+    
+    ARL --> VS
+    ARL --> VSC
+    ARL --> AZD
+    ARL --> AZCLI
+    ARL --> AZPS
+    
+    VS --> DevAccount
+    VSC --> DevAccount
+    AZD --> DevAccount
+    AZCLI --> DevAccount
+    AZPS --> DevAccount
+
+    DevAccount --> AS
+    
+    classDef highlight fill:#0078d4,stroke:#005ba1,stroke-width:2px,color:#fff,font-size:16px
+    classDef tools fill:#e6f3ff,stroke:#0078d4,stroke-width:1px,font-size:16px
+    classDef default font-size:16px
+    classDef lightgreen fill:#D4F4D4,stroke:#7BC97B,stroke-width:2px,color:#000,font-size:16px
+    
+    class AS highlight
+    class VS,VSC,AZD,AZCLI,AZPS tools
+    class LA,ARL default
+    class DevAccount lightgreen
+```
@@ -0,0 +1,28 @@
+---
+ms.topic: include
+ms.date: 08/07/2024
+---
+
+```mermaid
+%% STEPS TO GENERATE IMAGE 
+%% ======================= 
+%% 1. Install mermaid CLI v10.9.1 (see https://github.com/mermaid-js/mermaid-cli/blob/master/README.md): 
+%%    npm i -g @mermaid-js/mermaid-cli@10.9.1 
+%% 2. Run command: mmdc -i local-service-principal-authentication.md -o ../../media/mermaidjs/local-service-principal-authentication.svg 
+
+flowchart LR
+    APP["Local .NET app"]
+    SP["App service principal stored in environment variables"]
+    AS["Azure services"]
+
+    APP --> SP
+    SP --> AS
+
+    classDef app fill:#e6f3ff,stroke:#0078d4,stroke-width:2px,color:#000,font-size:16px
+    classDef serviceP fill:#D4F4D4,stroke:#7BC97B,stroke-width:2px,color:#000,font-size:16px
+    classDef services fill:#0078d4,stroke:#005ba1,stroke-width:2px,color:#fff,font-size:16px
+
+    class APP app
+    class SP serviceP
+    class AS services
+```