Clarify managed identities doc (dapr#4024)

* add more context

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* crosslink

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* Update daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/howto-mi.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>

* commiting before pulling in

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* update per bernd review

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* typo and emphasis

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

---------

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>
Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Co-authored-by: Mark Fussell <markfussell@gmail.com>

daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/authenticating-azure.md

@@ -106,7 +106,7 @@ When running on Kubernetes, you can also use references to Kubernetes secrets fo
 |-----------------|----------|----------------------------|------------------------------------------|
 | `azureClientId` | N        | Client ID (application ID) | `"c7dd251f-811f-4ba2-a905-acd4d3f8f08b"` |
 
-Using Managed Identities, the `azureClientId` field is generally recommended. The field is optional when using a system-assigned identity, but may be required when using user-assigned identities.
+[Using Managed Identities]({{< ref howto-mi.md >}}), the `azureClientId` field is generally recommended. The field is optional when using a system-assigned identity, but may be required when using user-assigned identities.
 
 #### Authenticating with Workload Identity on AKS
 

daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/howto-mi.md

@@ -1,18 +1,35 @@
 ---
 type: docs
-title: "How to: Use Managed Identities"
-linkTitle: "How to: Use MI"
+title: "How to: Use managed identities"
+linkTitle: "How to: Use managed identities"
 weight: 40000
 aliases:
   - "/developing-applications/integrations/azure/azure-authentication/howto-msi/"
-description: "Learn how to use Managed Identities"
+description: "Learn how to use managed identities"
 ---
 
-Using Managed Identities (MI), authentication happens automatically by virtue of your application running on top of an Azure service that has an assigned identity. 
+Using managed identities, authentication happens automatically by virtue of your application running on top of an Azure service that has either a system-managed or a user-assigned identity. 
 
-For example, let's say you enable a managed service identity for an Azure VM, Azure Container App, or an Azure Kubernetes Service cluster. When you do, an Microsoft Entra ID application is created for you and automatically assigned to the service. Your Dapr services can then leverage that identity to authenticate with Microsoft Entra ID, transparently and without you having to specify any credentials.
+To get started, you need to enable a managed identity as a service option/functionality in various Azure services, independent of Dapr. Enabling this creates an identity (or application) under the hood for Microsoft Entra ID (previously Azure Active Directory ID) purposes.
 
-To get started with managed identities, you need to assign an identity to a new or existing Azure resource. The instructions depend on the service use. Check the following official documentation for the most appropriate instructions:
+Your Dapr services can then leverage that identity to authenticate with Microsoft Entra ID, transparently and without you having to specify any credentials.
+
+In this guide, you learn how to:
+- Grant your identity to the Azure service you're using via official Azure documentation
+- Set up either a system-managed or user-assigned identity in your component
+
+
+That's about all there is to it.
+
+{{% alert title="Note" color="primary" %}}
+In your component YAML, you only need the [`azureClientId` property]({{< ref "authenticating-azure.md#authenticating-with-managed-identities-mi" >}}) if using user-assigned identity. Otherwise, you can omit this property for system-managed identity to be used by default.
+{{% /alert %}}
+
+## Grant access to the service
+
+Set the requisite Microsoft Entra ID role assignments or custom permissions to your system-managed or user-assigned identity for a particular Azure resource (as identified by the resource scope).
+
+You can set up a managed identity to a new or existing Azure resource. The instructions depend on the service use. Check the following official documentation for the most appropriate instructions:
 
 - [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/azure/aks/use-managed-identity)
 - [Azure Container Apps (ACA)](https://learn.microsoft.com/azure/container-apps/dapr-overview?tabs=bicep1%2Cyaml#using-managed-identity)
@@ -21,9 +38,7 @@ To get started with managed identities, you need to assign an identity to a new
 - [Azure Virtual Machines Scale Sets (VMSS)](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-cli-windows-vmss)
 - [Azure Container Instance (ACI)](https://docs.microsoft.com/azure/container-instances/container-instances-managed-identity)
 
-Dapr supports both system-assigned and user-assigned identities.
-
-After assigning an identity to your Azure resource, you will have credentials such as:
+After assigning a system-managed identity to your Azure resource, you'll have credentials like the following:
 
 ```json
 {
@@ -34,7 +49,95 @@ After assigning an identity to your Azure resource, you will have credentials su
 }
 ```
 
-From the returned values, take note of **`principalId`**, which is the Service Principal ID that was created. You'll use that to grant access to Azure resources to your identity.
+From the returned values, take note of the **`principalId`** value, which is [the Service Principal ID created for your identity]({{< ref "howto-aad.md#create-a-service-principal" >}}). Use that to grant access permissions for your Azure resources component to access the identity.
+
+{{% alert title="Managed identities in Azure Container Apps" color="primary" %}}
+Every container app has a completely different system-managed identity, making it very unmanageable to handle the required role assignments across multiple apps. 
+
+Instead, it's _strongly recommended_ to use a user-assigned identity and attach this to all the apps that should load the component. Then, you should scope the component to those same apps.
+{{% /alert %}}
+
+## Set up identities in your component
+
+By default, Dapr Azure components look up the system-managed identity of the environment they run in and authenticate as that. Generally, for a given component, there are no required properties to use system-managed identity other than the service name, storage account name, and any other properites required by the Azure service (listed in the documentation). 
+
+For user-assigned idenitities, in addition to the basic properties required by the service you're using, you need to specify the `azureClientId` (user-assigned identity ID) in the component. Make sure the user-assigned identity is attached to the Azure service Dapr is running on, or else you won't be able to use that identity.
+
+{{% alert title="Note" color="primary" %}}
+If the sidecar loads a component which does not specify `azureClientId`, it only tries the system-assigned identity. If the component specifies the `azureClientId` property, it only tries the particular user-assigned identity with that ID.
+{{% /alert %}}
+
+The following examples demonstrate setting up either a system-managed or user-assigned identity in an Azure KeyVault secrets component.
+
+{{< tabs "System-managed" "User-assigned" "Kubernetes" >}}
+
+ <!-- system managed -->
+{{% codetab %}}
+
+If you set up system-managed identity using an Azure KeyVault component, the YAML would look like the following:
+
+```yml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: azurekeyvault
+spec:
+  type: secretstores.azure.keyvault
+  version: v1
+  metadata:
+  - name: vaultName
+    value: mykeyvault
+```
+
+In this example, the system-managed identity looks up the service identity and communicates with the `mykeyvault` vault. Next, grant your system-managed identiy access to the desired service.
+
+{{% /codetab %}}
+
+ <!-- user assigned -->
+{{% codetab %}}
+
+If you set up user-assigned identity using an Azure KeyVault component, the YAML would look like the following:
+
+```yml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: azurekeyvault
+spec:
+  type: secretstores.azure.keyvault
+  version: v1
+  metadata:
+  - name: vaultName
+    value: mykeyvault
+  - name: azureClientId
+    value: someAzureIdentityClientIDHere
+```
+
+Once you've set up the component YAML with the `azureClientId` property, you can grant your user-assigned identity access to your service.
+
+{{% /codetab %}}
+
+ <!-- k8s -->
+{{% codetab %}}
+
+For component configuration in Kubernetes or AKS, refer to the [Workload Identity guidance.](https://learn.microsoft.com/azure/aks/workload-identity-overview?tabs=dotnet)
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Troubleshooting
+
+If you receive an error or your managed identity doesn't work as expected, check if the following items are true:
+
+- The system-managed identity or user-assigned identity don't have the required permissions on the target resource.
+- The user-assigned identity isn't attached to the Azure service (container app or pod) from which you're loading the component. This can especially happen if:
+  - You have an unscoped component (a component loaded by all container apps in an environment, or all deployments in your AKS cluster). 
+  - You attached the user-assigned identity to only one container app or one deployment in AKS (using [Azure Workload Identity](https://learn.microsoft.com/azure/aks/workload-identity-overview?tabs=dotnet)). 
+
+  In this scenario, since the identity isn't attached to every other container app or deployment in AKS, the component referencing the user-assigned identity via `azureClientId` fails.
+
+> **Best practice:** When using user-assigned identities, make sure to scope your components to specific apps!
 
 ## Next steps
 

daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md

@@ -74,7 +74,7 @@ The `-k` flag initializes Dapr on the Kubernetes cluster in your current context
 
 #### Install Dapr from a private Dapr Helm chart
 
-Installing Dapr from a private Helm chart can be helpful for when you:
+Installing [Dapr from a private Helm chart](#install-dapr-from-an-official-dapr-helm-chart) can be helpful for when you:
 - Need more granular control of the Dapr Helm chart
 - Have a custom Dapr deployment
 - Pull Helm charts from trusted registries that are managed and maintained by your organization