docs(azure): enhance Managed Identity authentication documentation

docs/user-guide/providers/azure/authentication.mdx

@@ -246,12 +246,223 @@ prowler azure --az-cli-auth
 
 *Available only for Prowler CLI*
 
-Authenticate via Azure Managed Identity (when running on Azure resources):
+Authenticate via Azure Managed Identity when running Prowler on Azure resources (VMs, Container Instances, Azure Functions, etc.):
 
 ```console
 prowler azure --managed-identity-auth
 ```
 
+### Prerequisites
+
+Before using Managed Identity authentication, you need to:
+
+1. **Enable Managed Identity** on your Azure resource (e.g., VM, Container Instance)
+2. **Assign the required permissions** to the Managed Identity on the target subscription(s) you want to scan
+
+<Warning>
+A common misconception is that enabling a Managed Identity on a resource automatically grants it permissions. **This is not the case.** The Managed Identity itself is a service principal that must be explicitly granted Reader and ProwlerRole permissions on each subscription you want to scan.
+</Warning>
+
+### Step-by-Step Setup Guide
+
+#### Step 1: Enable Managed Identity on Your Azure Resource
+
+<Tabs>
+  <Tab title="Azure VM">
+    **Via Azure Portal:**
+    1. Navigate to your VM in the Azure Portal
+    2. Select "Identity" from the left menu under "Security"
+    3. Under "System assigned" tab, set Status to "On"
+    4. Click "Save"
+    5. Note the "Object (principal) ID" - you'll need this for permission assignment
+
+    **Via Azure CLI:**
+    ```console
+    # Enable system-assigned managed identity
+    az vm identity assign --name <vm-name> --resource-group <resource-group>
+
+    # Get the principal ID
+    az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv
+    ```
+  </Tab>
+  <Tab title="Azure Container Instance">
+    **Via Azure CLI:**
+    ```console
+    # Enable system-assigned managed identity
+    az container create \
+      --resource-group <resource-group> \
+      --name <container-name> \
+      --image <image> \
+      --assign-identity
+
+    # Get the principal ID
+    az container show --resource-group <resource-group> --name <container-name> --query identity.principalId -o tsv
+    ```
+  </Tab>
+</Tabs>
+
+#### Step 2: Assign Reader Role to the Managed Identity
+
+The Managed Identity needs the **Reader** role on each subscription you want to scan. You must assign this role to the **Managed Identity's principal ID**, not the VM or resource itself.
+
+<Tabs>
+  <Tab title="Azure Portal">
+    1. Navigate to the **target subscription** you want to scan (not the VM's resource group)
+    2. Select "Access control (IAM)" from the left menu
+    3. Click "+ Add" > "Add role assignment"
+    4. Select "Reader" role, click "Next"
+    5. Click "+ Select members"
+    6. Search for your VM name or paste the Managed Identity's Object/Principal ID
+    7. Select it and click "Select"
+    8. Click "Review + assign"
+
+    <Note>
+    If you're scanning a subscription different from where your VM is located, make sure you're assigning the role on the **target subscription**, not the VM's subscription.
+    </Note>
+  </Tab>
+  <Tab title="Azure CLI">
+    ```console
+    # Get the principal ID of your resource's managed identity
+    PRINCIPAL_ID=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)
+
+    # Assign Reader role on the target subscription
+    az role assignment create \
+      --role "Reader" \
+      --assignee-object-id $PRINCIPAL_ID \
+      --assignee-principal-type ServicePrincipal \
+      --scope /subscriptions/<target-subscription-id>
+    ```
+  </Tab>
+</Tabs>
+
+#### Step 3: Create and Assign ProwlerRole to the Managed Identity
+
+The ProwlerRole is a custom role required for specific security checks. First, create the role if it doesn't exist, then assign it to your Managed Identity.
+
+<Tabs>
+  <Tab title="Azure CLI">
+    **Create the ProwlerRole:**
+    ```console
+    az role definition create --role-definition '{
+      "Name": "ProwlerRole",
+      "IsCustom": true,
+      "Description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
+      "AssignableScopes": ["/subscriptions/<target-subscription-id>"],
+      "Actions": [
+        "Microsoft.Web/sites/host/listkeys/action",
+        "Microsoft.Web/sites/config/list/Action"
+      ]
+    }'
+    ```
+
+    **Assign ProwlerRole to the Managed Identity:**
+    ```console
+    # Get the principal ID if you don't have it
+    PRINCIPAL_ID=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)
+
+    # Assign ProwlerRole on the target subscription
+    az role assignment create \
+      --role "ProwlerRole" \
+      --assignee-object-id $PRINCIPAL_ID \
+      --assignee-principal-type ServicePrincipal \
+      --scope /subscriptions/<target-subscription-id>
+    ```
+  </Tab>
+  <Tab title="Azure Portal">
+    Follow the same process as creating the ProwlerRole in the [Assigning ProwlerRole Permissions](/user-guide/providers/azure/authentication#assigning-prowlerrole-permissions-at-the-subscription-level) section, then assign it to your Managed Identity using the same steps as the Reader role assignment.
+  </Tab>
+</Tabs>
+
+#### Step 4: (Optional) Assign Microsoft Graph Permissions
+
+For Entra ID (Azure AD) checks, the Managed Identity needs Microsoft Graph API permissions: `Directory.Read.All`, `Policy.Read.All`, and optionally `UserAuthenticationMethod.Read.All`.
+
+<Note>
+Assigning Microsoft Graph API permissions to a Managed Identity requires Azure CLI or PowerShell - it cannot be done through the Azure Portal's standard role assignment interface.
+</Note>
+
+```console
+# Get the Managed Identity's principal ID
+PRINCIPAL_ID=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)
+
+# Get Microsoft Graph's service principal ID
+GRAPH_SP_ID=$(az ad sp list --display-name "Microsoft Graph" --query [0].id -o tsv)
+
+# Assign Directory.Read.All permission (App Role ID: 7ab1d382-f21e-4acd-a863-ba3e13f7da61)
+az rest --method POST \
+  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$PRINCIPAL_ID/appRoleAssignments" \
+  --headers "Content-Type=application/json" \
+  --body "{\"principalId\": \"$PRINCIPAL_ID\", \"resourceId\": \"$GRAPH_SP_ID\", \"appRoleId\": \"7ab1d382-f21e-4acd-a863-ba3e13f7da61\"}"
+
+# Assign Policy.Read.All permission (App Role ID: 246dd0d5-5bd0-4def-940b-0421030a5b68)
+az rest --method POST \
+  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$PRINCIPAL_ID/appRoleAssignments" \
+  --headers "Content-Type=application/json" \
+  --body "{\"principalId\": \"$PRINCIPAL_ID\", \"resourceId\": \"$GRAPH_SP_ID\", \"appRoleId\": \"246dd0d5-5bd0-4def-940b-0421030a5b68\"}"
+```
+
+#### Step 5: Run Prowler
+
+SSH or connect to your Azure resource and run Prowler:
+
+```console
+# Scan all accessible subscriptions
+prowler azure --managed-identity-auth
+
+# Scan specific subscription(s)
+prowler azure --managed-identity-auth --subscription-ids <subscription-id>
+```
+
+<Note>
+Wait a few minutes after assigning roles for Azure to propagate permissions. Role assignments are not always immediately effective.
+</Note>
+
+### Troubleshooting
+
+#### Error: "No subscriptions were found, please check your permission assignments"
+
+**Cause:** The Managed Identity doesn't have the Reader role assigned on any subscription.
+
+**Solution:**
+- Verify the Managed Identity has the Reader role assigned on at least one subscription
+- Wait a few minutes after role assignment for Azure to propagate permissions
+- Verify role assignments:
+  ```console
+  az role assignment list --assignee <principal-id> --all
+  ```
+
+#### Error: "does not have authorization to perform action 'Microsoft.Resources/subscriptions/read'"
+
+**Cause:** The Managed Identity lacks the Reader role on the target subscription.
+
+**Solution:**
+- Ensure you assigned the Reader role to the **Managed Identity's principal ID**, not the VM resource
+- Verify you're assigning the role on the **target subscription** you want to scan, not just the VM's resource group
+- Check role assignments:
+  ```console
+  az role assignment list --assignee <principal-id> --scope /subscriptions/<subscription-id>
+  ```
+
+#### Error: "CredentialUnavailableError: ManagedIdentityCredential authentication unavailable"
+
+**Cause:** Managed Identity is not enabled on the resource, or you're running Prowler outside of Azure.
+
+**Solution:**
+- Verify Managed Identity is enabled on your Azure resource
+- Ensure you're running Prowler from within the Azure resource (not your local machine)
+- Check Managed Identity status:
+  ```console
+  az vm identity show --name <vm-name> --resource-group <resource-group>
+  ```
+
+#### Error: Access token validation failure for Entra ID checks
+
+**Cause:** The Managed Identity lacks Microsoft Graph API permissions.
+
+**Solution:**
+- Assign the required Graph API permissions as shown in Step 4
+- These permissions are optional for basic resource scanning but required for Entra ID security checks
+
 ## Browser Authentication
 
 *Available only for Prowler CLI*