Update user-assigned and system-assigned managed identity code, overview edits (#44872)

* Update identity guidance and instructions


---------

Co-authored-by: Scott Addie <[email protected]>
Co-authored-by: Christopher Scott <[email protected]>

Author: 3 people

docs/azure/sdk/authentication/index.md

@@ -6,59 +6,76 @@ ms.custom: devx-track-dotnet, engagement-fy23
 ms.date: 08/02/2024
 ---
 
-# Authenticate .NET apps to Azure services using the Azure Identity library overview
+# Authenticate .NET apps to Azure services using the Azure Identity library
 
-When an app needs to access an Azure resource, the app must be authenticated to Azure. This is true for all apps, whether deployed to Azure, deployed on-premises, or under development on a local developer workstation. This article describes the recommended approaches to authenticate an app to Azure when using the Azure SDK client libraries.
+Apps can use the Azure Identity library to authenticate to Microsoft Entra ID, which allows the apps to access Azure services and resources. This authentication requirement applies whether the app is deployed to Azure, hosted on-premises, or running locally on a developer workstation. The sections ahead describe the recommended approaches to authenticate an app to Microsoft Entra ID across different environments when using the Azure SDK client libraries.
 
-## Recommended app authentication approach
+## Recommended approach for app authentication
 
-It's recommended that apps use token-based authentication rather than connection strings when authenticating to Azure resources. The [Azure Identity library](/dotnet/api/overview/azure/identity-readme?view=azure-dotnet&preserve-view=true) provides classes that support token-based authentication and allow apps to seamlessly authenticate to Azure resources whether the app is in local development, deployed to Azure, or deployed to an on-premises server.
+Token-based authentication via Microsoft Entra ID is the recommended approach for authenticating apps to Azure, instead of using connection strings or key-based options. The [Azure Identity library](/dotnet/api/overview/azure/identity-readme?view=azure-dotnet&preserve-view=true) provides classes that support token-based authentication and allow apps to authenticate to Azure resources whether the app runs locally, on Azure, or on an on-premises server.
 
-The specific type of token-based authentication an app should use to authenticate to Azure resources depends on where the app runs and is shown in the following diagram:
+### Advantages of token-based authentication
+
+Token-based authentication offers the following advantages over connection strings:
+
+- Token-based authentication ensures only the specific apps intended to access the Azure resource are able to do so, whereas anyone or any app with a connection string can connect to an Azure resource.
+- Token-based authentication allows you to further limit Azure resource access to only the specific permissions needed by the app. This follows the [principle of least privilege](https://wikipedia.org/wiki/Principle_of_least_privilege). In contrast, a connection string grants full rights to the Azure resource.
+- When using a [managed identity](/entra/identity/managed-identities-azure-resources/overview) for token-based authentication, Azure handles administrative functions for you, so you don't have to worry about tasks like securing or rotating secrets. This makes the app more secure because there's no connection string or application secret that can be compromised.
+- The Azure Identity library acquires and manages Microsoft Entra tokens for you.
+
+Use of connection strings should be limited to scenarios where token-based authentication is not an option, initial proof-of-concept apps, or development prototypes that don't access production or sensitive data. When possible, use the token-based authentication classes available in the Azure Identity library to authenticate to Azure resources.
+
+## Authentication across different environments
+
+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." :::
 
 When an app is:
 
-- **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 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-in-server-environments).
-- **Hosted and deployed on-premises**, the app should authenticate to Azure resources using an application service principal. This option is discussed in more detail at [authentication in server environments](#authentication-in-server-environments).
+- **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).
 
-### DefaultAzureCredential
+## Authentication for Azure-hosted apps
 
-The [DefaultAzureCredential](#use-defaultazurecredential-in-an-application) class provided by the Azure Identity library allows apps to use different authentication methods depending on the environment in which they're run. This allows apps to be promoted from local development to test environments to production without code changes. You configure the appropriate authentication method for each environment, and `DefaultAzureCredential` will automatically detect and use that authentication method. The use of `DefaultAzureCredential` should be preferred over manually coding conditional logic or feature flags to use different authentication methods in different environments.
+When your app is hosted on Azure, it can use managed identities to authenticate to Azure resources without needing to manage any credentials. There are two types of managed identities: user-assigned and system-assigned.
 
-Details about using `DefaultAzureCredential` are covered at [Use `DefaultAzureCredential` in an application](#use-defaultazurecredential-in-an-application).
+#### Use a user-assigned managed identity
 
-### Advantages of token-based authentication
+A user-assigned managed identity is created as a standalone Azure resource. It can be assigned to one or more Azure resources, allowing those resources to share the same identity and permissions. To authenticate using a user-assigned managed identity, create the identity, assign it to your Azure resource, and then configure your app to use this identity for authentication by specifying its client ID, resource ID, or object ID.
 
-Token-based authentication offers the following advantages over authenticating with connection strings:
+> [!div class="nextstepaction"]
+> [Authenticate using a user-assigned managed identity](user-assigned-managed-identity.md)
 
-- The token-based authentication methods described below allows you to establish the specific permissions needed by the app on the Azure resource. This follows the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). In contrast, a connection string grants full rights to the Azure resource.
-- Whereas anyone or any app with a connection string can connect to an Azure resource, token-based authentication methods scope access to the resource to only the app(s) intended to access the resource.  
-- In the case of a managed identity, there's no application secret to store. This makes the app more secure because there's no connection string or application secret that can be compromised.
-- The [Azure.Identity](https://www.nuget.org/packages/Azure.Identity) package acquires and manages Microsoft Entra tokens for you. This makes using token-based authentication as easy to use as a connection string.
+#### Use a system-assigned managed identity
 
-Use of connection strings should be limited to initial proof-of-concept apps or development prototypes that don't access production or sensitive data. Otherwise, the token-based authentication classes available in the Azure Identity library should always be preferred when authenticating to Azure resources.
+A system-assigned managed identity is enabled directly on an Azure resource. The identity is tied to the lifecycle of that resource and is automatically deleted when the resource is deleted. To authenticate using a system-assigned managed identity, enable the identity on your Azure resource and then configure your app to use this identity for authentication.
 
-## Authentication in server environments
+> [!div class="nextstepaction"]
+> [Authenticate using a system-assigned managed identity](system-assigned-managed-identity.md)
 
-When hosting in a server environment, each app should be assigned a unique *application identity* per environment in which the app is run. In Azure, an application identity is represented by a **service principal**, a special type of *security principal* intended to identify and authenticate apps to Azure. The type of service principal to use for your app depends on where your app is running.
+## Authentication during local development
 
-| Authentication method | Description |
-|-----------------------|-------------|
-| Apps hosted in Azure  | [!INCLUDE [sdk-auth-overview-managed-identity](../includes/sdk-auth-overview-managed-identity.md)]            |
-| Apps hosted outside of Azure<br>(for example, on-premises apps) | [!INCLUDE [sdk-auth-overview-service-principal](../includes/sdk-auth-overview-service-principal.md)] |
+During local development, you can authenticate to Azure resources using your developer credentials or a service principal. This allows you to test your app's authentication logic without deploying it to Azure.
 
-## Authentication during local development
+#### Use developer credentials
+
+You can use your own Azure credentials to authenticate to Azure resources during local development. This is typically done using a development tool, such as Azure CLI or Visual Studio, which can provide your app with the necessary tokens to access Azure services. This method is convenient but should only be used for development purposes.
+
+> [!div class="nextstepaction"]
+> [Authenticate locally using developer credentials](local-development-dev-accounts.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.
 
-When an app is run on a developer's workstation during local development, it must still authenticate to any Azure services used by the app. The two main strategies for authenticating apps to Azure during local development are:
+> [!div class="nextstepaction"]
+> [Authenticate locally using a service principal](local-development-service-principal.md)
 
-| Authentication method | Description |
-|-----------------------|-------------|
-| Create dedicated application service principal objects to be used during local development | [!INCLUDE [sdk-auth-overview-dev-service-principals](../includes/sdk-auth-overview-dev-service-principals.md)] |
-| Authenticate the app to Azure using the developer's credentials during local development | [!INCLUDE [sdk-auth-overview-dev-accounts](../includes/sdk-auth-overview-dev-accounts.md)] |
+## Authentication for apps hosted on-premises
 
-## Use DefaultAzureCredential in an application
+For apps hosted on-premises, you can use a service principal to authenticate to Azure resources. This involves creating a service principal in Microsoft Entra ID, assigning it the necessary permissions, and configuring your app to use its credentials. This method allows your on-premises app to securely access Azure services.
 
-[!INCLUDE [Implement DefaultAzureCredential](<../includes/implement-defaultazurecredential.md>)]
+> [!div class="nextstepaction"]
+> [Authenticate your on-prem app using a service principal](local-development-service-principal.md)

docs/azure/sdk/authentication/system-assigned-managed-identity.md

@@ -32,7 +32,7 @@ You can enable a system-assigned managed identity for an Azure resource using ei
 1. On the **Identity** page, toggle the **Status** slider to **On**.
 1. Select **Save** to apply your changes.
 
-    :::image type="content" source="../media/system-assigned-identity-enable.png" alt-text="A screenshot showing how to enable a system-assigned identity on a container app.":::
+    :::image type="content" source="../media/system-assigned-identity-enable.png" alt-text="A screenshot showing how to enable a system-assigned managed identity on a container app.":::
 
 ### [Azure CLI](#tab/azure-cli)
 
@@ -133,6 +133,4 @@ For information on assigning permissions at the resource or subscription level u
 
 ---
 
-## Implement DefaultAzureCredential in your application
-
-[!INCLUDE [Implement DefaultAzureCredential](<../includes/implement-defaultazurecredential.md>)]
+[!INCLUDE [Implement user-assigned managed identity](<../includes/implement-system-assigned-identity.md>)]