diff --git a/docs/azure/sdk/authentication/index.md b/docs/azure/sdk/authentication/index.md index 62ef20f31a4b7..c447ef961bd91 100644 --- a/docs/azure/sdk/authentication/index.md +++ b/docs/azure/sdk/authentication/index.md @@ -32,13 +32,13 @@ 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: - **Hosted on Azure**: The app should authenticate to Azure resources using a managed identity. This option is discussed in more detail at [authentication in server environments](#authentication-for-azure-hosted-apps). -- **Running locally during development**: The app can authenticate to Azure using either an application service principal for local development or by using the developer's Azure credentials. Each option is discussed in more detail at [authentication during local development](#authentication-during-local-development). -- **Hosted on-premises**: The app should authenticate to Azure resources using an application service principal, or a managed identity in the case of Azure Arc. On-premises workflows are discussed in more detail at [authentication in server environments](#authentication-for-apps-hosted-on-premises). +- **Running locally during development**: The app can authenticate to Azure using a [developer account](local-development-dev-accounts.md), a [broker](local-development-broker.md), or a [service principal](local-development-service-principal.md). Each option is discussed in more detail at [authentication during local development](#authentication-during-local-development). +- **Hosted on-premises**: The app should authenticate to Azure resources using an application service principal, or a managed identity in the case of Azure Arc. On-premises workflows are discussed in more detail at [Authentication for apps hosted on-premises](#authentication-for-apps-hosted-on-premises). ## Authentication for Azure-hosted apps @@ -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. diff --git a/docs/azure/sdk/authentication/local-development-dev-accounts.md b/docs/azure/sdk/authentication/local-development-dev-accounts.md index 4c32dcaae1c7f..b6504fcb876a2 100644 --- a/docs/azure/sdk/authentication/local-development-dev-accounts.md +++ b/docs/azure/sdk/authentication/local-development-dev-accounts.md @@ -12,14 +12,20 @@ ms.custom: # Authenticate .NET apps to Azure services during local development using developer accounts -During local development, applications need to authenticate to Azure to access various Azure services. Two common approaches for local authentication are to [use a service principal](local-development-service-principal.md) or to use a developer account. This article explains how to use a developer account. In the sections ahead, you learn: +During local development, applications need to authenticate to Azure to use different Azure services. Authenticate locally using one of these approaches: -- How to use Microsoft Entra groups to efficiently manage permissions for multiple developer accounts -- How to assign roles to developer accounts to scope permissions -- How to sign-in to supported local development tools -- How to authenticate using a developer account from your app code +- Use a developer account with one of the [developer tools supported by the Azure Identity library](#supported-developer-tools-for-authentication). +- Use a [broker](local-development-broker.md) to manage credentials. +- Use a [service principal](local-development-service-principal.md). -:::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."::: +This article explains how to authenticate using a developer account with tools supported by the Azure Identity library. In the sections ahead, you learn: + +- How to use Microsoft Entra groups to efficiently manage permissions for multiple developer accounts. +- How to assign roles to developer accounts to scope permissions. +- How to sign-in to supported local development tools. +- How to authenticate using a developer account from your app code. + +## Supported developer tools for authentication 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: @@ -27,6 +33,7 @@ For an app to authenticate to Azure during local development using the developer - 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. @@ -44,9 +51,30 @@ Next, sign-in to Azure using one of several developer tools that can be used to [!INCLUDE [auth-visual-studio](../includes/auth-visual-studio.md)] +### [Visual Studio Code](#tab/sign-in-visual-studio-code) + +Developers using Visual Studio Code can authenticate with their developer account directly through the editor via the broker. Apps that use or can then use this account to authenticate app requests through a seamless single-sign-on experience. + +1. In Visual Studio Code, go to the **Extensions** panel and install the [Azure Resources](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureresourcegroups) extension. This extension lets you view and manage Azure resources directly from Visual Studio Code. It also uses the built-in Visual Studio Code Microsoft authentication provider to authenticate with Azure. + + :::image type="content" source="../media/azure-resources-extension.png" alt-text="Screenshot showing the Azure Resources extension."::: + +1. Open the Command Palette in Visual Studio Code, then search for and select **Azure: Sign in**. + + :::image type="content" source="../media/visual-studio-code-sign-in.png" alt-text="Screenshot showing how to sign in to Azure in Visual Studio Code."::: + + > [!TIP] + > Open the Command Palette using `Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS. + +1. Add the [Azure.Identity.Broker](https://www.nuget.org/packages/Azure.Identity.Broker) NuGet package to your app: + + ```dotnetcli + dotnet add package Azure.Identity.Broker + ``` + ### [Azure CLI](#tab/sign-in-azure-cli) -Developers coding outside of an IDE can also use the [Azure CLI](/cli/azure/what-is-azure-cli) to authenticate. Apps using `DefaultAzureCredential` or can then use this account to authenticate app requests when running locally. +Developers can use [Azure CLI](/cli/azure/what-is-azure-cli) to authenticate. Apps using or can then use this account to authenticate app requests. To authenticate with the Azure CLI, run the `az login` command. On a system with a default web browser, the Azure CLI launches the browser to authenticate the user. @@ -62,7 +90,7 @@ az login --use-device-code ### [Azure Developer CLI](#tab/sign-in-azure-developer-cli) -Developers coding outside of an IDE can also use the [Azure Developer CLI](/azure/developer/azure-developer-cli/overview) to authenticate. Apps using `DefaultAzureCredential` or can then use this account to authenticate app requests when running locally. +Developers can use [Azure Developer CLI](/azure/developer/azure-developer-cli/overview) to authenticate. Apps using or can then use this account to authenticate app requests. To authenticate with the Azure Developer CLI, run the `azd auth login` command. On a system with a default web browser, the Azure Developer CLI launches the browser to authenticate the user. @@ -70,7 +98,7 @@ To authenticate with the Azure Developer CLI, run the `azd auth login` command. azd auth login ``` -For systems without a default web browser, the `azd auth login --use-device-code` uses the device code authentication flow. The user can also force the the Azure Developer CLI to use the device code flow rather than launching a browser by specifying the `--use-device-code` argument. +For systems without a default web browser, the `azd auth login --use-device-code` uses the device code authentication flow. The user can also force the Azure Developer CLI to use the device code flow rather than launching a browser by specifying the `--use-device-code` argument. ```azdeveloper azd auth login --use-device-code @@ -78,7 +106,7 @@ azd auth login --use-device-code ### [Azure PowerShell](#tab/sign-in-azure-powershell) -Developers coding outside of an IDE can also use [Azure PowerShell](/powershell/azure/what-is-azure-powershell) to authenticate. Apps using `DefaultAzureCredential` or can then use this account to authenticate app requests when running locally. +Developers can use [Azure PowerShell](/powershell/azure/what-is-azure-powershell) to authenticate. Apps using or can then use this account to authenticate app requests. To authenticate with Azure PowerShell, run the command `Connect-AzAccount`. On a system with a default web browser and version 5.0.0 or later of Azure PowerShell, it launches the browser to authenticate the user. diff --git a/docs/azure/sdk/authentication/local-development-service-principal.md b/docs/azure/sdk/authentication/local-development-service-principal.md index ad2d72f367964..ba7aca1f8440b 100644 --- a/docs/azure/sdk/authentication/local-development-service-principal.md +++ b/docs/azure/sdk/authentication/local-development-service-principal.md @@ -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: diff --git a/docs/azure/sdk/media/azure-resources-extension.png b/docs/azure/sdk/media/azure-resources-extension.png new file mode 100644 index 0000000000000..e1f5e93d5654d Binary files /dev/null and b/docs/azure/sdk/media/azure-resources-extension.png differ diff --git a/docs/azure/sdk/media/broker-macos-account-picker.png b/docs/azure/sdk/media/broker-macos-account-picker.png index 9f5bc85fefa42..4cf2af2e971ce 100644 Binary files a/docs/azure/sdk/media/broker-macos-account-picker.png and b/docs/azure/sdk/media/broker-macos-account-picker.png differ diff --git a/docs/azure/sdk/media/dotnet-sdk-auth-strategy.png b/docs/azure/sdk/media/dotnet-sdk-auth-strategy.png deleted file mode 100644 index 6ac249515441d..0000000000000 Binary files a/docs/azure/sdk/media/dotnet-sdk-auth-strategy.png and /dev/null differ diff --git a/docs/azure/sdk/media/local-dev-dev-accounts-overview.png b/docs/azure/sdk/media/local-dev-dev-accounts-overview.png deleted file mode 100644 index 7fa06e7407b4c..0000000000000 Binary files a/docs/azure/sdk/media/local-dev-dev-accounts-overview.png and /dev/null differ diff --git a/docs/azure/sdk/media/mermaidjs/authentication-environments.md b/docs/azure/sdk/media/mermaidjs/authentication-environments.md new file mode 100644 index 0000000000000..f5584204408fd --- /dev/null +++ b/docs/azure/sdk/media/mermaidjs/authentication-environments.md @@ -0,0 +1,48 @@ +--- +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 --> UserPrincipal["**User principal**"] + + %% Azure Branch + Q1 --> AzureApp[Azure] + AzureApp --> ManagedId["**Managed identity**"] + + + %% On-premises Server Branch + Q1 --> OnPremApp[On-premises server] + OnPremApp --> ServicePrincipal["**Service principal**"] + OnPremApp --> ArcManagedId["**Managed identity (Azure Arc only)**"] + + %% 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,UserPrincipal,ManagedId,ServicePrincipal,ArcManagedId authMethod + class LocalDev,AzureApp,OnPremApp envNode +``` diff --git a/docs/azure/sdk/media/mermaidjs/authentication-environments.svg b/docs/azure/sdk/media/mermaidjs/authentication-environments.svg new file mode 100644 index 0000000000000..de2202d029f74 --- /dev/null +++ b/docs/azure/sdk/media/mermaidjs/authentication-environments.svg @@ -0,0 +1 @@ +

.NET app

Where is the app running?

Development machine

Service principal

User principal

Azure

Managed identity

On-premises server

Service principal

Managed identity (Azure Arc only)

\ No newline at end of file diff --git a/docs/azure/sdk/media/mermaidjs/local-service-principal-authentication.md b/docs/azure/sdk/media/mermaidjs/local-service-principal-authentication.md new file mode 100644 index 0000000000000..18c470a0e76d8 --- /dev/null +++ b/docs/azure/sdk/media/mermaidjs/local-service-principal-authentication.md @@ -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 +``` diff --git a/docs/azure/sdk/media/mermaidjs/local-service-principal-authentication.svg b/docs/azure/sdk/media/mermaidjs/local-service-principal-authentication.svg new file mode 100644 index 0000000000000..5cb39256f01c2 --- /dev/null +++ b/docs/azure/sdk/media/mermaidjs/local-service-principal-authentication.svg @@ -0,0 +1 @@ +

Local .NET app

App service principal stored in environment variables

Azure services

\ No newline at end of file diff --git a/docs/azure/sdk/media/visual-studio-code-sign-in.png b/docs/azure/sdk/media/visual-studio-code-sign-in.png new file mode 100644 index 0000000000000..e4a54866c2208 Binary files /dev/null and b/docs/azure/sdk/media/visual-studio-code-sign-in.png differ