Documentation: Clarify managed identity credential types for containerized vs. VM/App Service deployments

src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md

@@ -56,25 +56,54 @@ services.AddAgentIdentities();
 
 Configure your agent identity blueprint application with the necessary credentials using appsettings.json:
 
+**Using Client Certificate:**
 ```json
 {
   "AzureAd": {
     "Instance": "https://login.microsoftonline.com/",
     "TenantId": "your-tenant-id",
     "ClientId": "agent-application-client-id",
-
     "ClientCredentials": [
       {
         "SourceType": "StoreWithDistinguishedName",
         "CertificateStorePath": "LocalMachine/My",
         "CertificateDistinguishedName": "CN=YourCertificateName"
       }
+    ]
+  }
+}
+```
+
+**Using Managed Identity (deployment scenario-specific):**
 
-      // Or for Federation Identity Credential with Managed Identity:
-      // {
-      //   "SourceType": "SignedAssertionFromManagedIdentity",
-      //   "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
-      // }
+For **containerized environments** (Kubernetes, AKS, Docker) with **Azure AD Workload Identity**, use `SignedAssertionFilePath`:
+```json
+{
+  "AzureAd": {
+    "Instance": "https://login.microsoftonline.com/",
+    "TenantId": "your-tenant-id",
+    "ClientId": "agent-application-client-id",
+    "ClientCredentials": [
+      {
+        "SourceType": "SignedAssertionFilePath",
+      }
+    ]
+  }
+}
+```
+
+For **classic managed identity scenarios** (VMs, App Services) use `SignedAssertionFromManagedIdentity`:
+```json
+{
+  "AzureAd": {
+    "Instance": "https://login.microsoftonline.com/",
+    "TenantId": "your-tenant-id",
+    "ClientId": "agent-application-client-id",
+    "ClientCredentials": [
+      {
+        "SourceType": "SignedAssertionFromManagedIdentity",
+        "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
+      }
     ]
   }
 }
@@ -97,9 +126,14 @@ services.Configure<MicrosoftIdentityApplicationOptions>(
     });
 ```
 
-See https://aka.ms/ms-id-web/credential-description for all the ways to express credentials.
+**Important Notes on Credential Types:**
+- For comprehensive credential configuration options, see the [CredentialDescription documentation](https://aka.ms/ms-id-web/credential-description)
+- For containerized workloads (Kubernetes, AKS, Docker), always use `SignedAssertionFilePath` with Azure AD Workload Identity
+- The `SignedAssertionFilePath` points to the projected service account token, typically mounted at `/var/run/secrets/azure/tokens/azure-identity-token`
+- Only use `SignedAssertionFromManagedIdentity` for classic managed identity scenarios on VMs or App Services
+- For detailed guidance on workload identity, see [Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/)
 
-On ASP.NET Core, use the override of services.Configure taking an authentication scheeme. Youy can also
+On ASP.NET Core, use the override of services.Configure taking an authentication scheme. You can also
 use Microsoft.Identity.Web.Owin if you have an ASP.NET Core application on OWIN (not recommended for new
 apps), or even create a daemon application.
 

src/Microsoft.Identity.Web.Sidecar/README.md

@@ -65,10 +65,43 @@ dotnet run -f net9.0
 
 ### Containers
 
+The sidecar is designed to run in containerized environments. Choose the appropriate Dockerfile for your target platform:
+
 - [Dockerfile](./Dockerfile) is used for building images within Visual Studio
 - [DockerFile.NanoServer](./DockerFile.NanoServer) is used for building a nanoserver image from previously build binaries
 - [DockerFile.AzureLinux](./Dockerfile.AzureLinux) is used for building an azure linux 3.0 image from previously build binaries
 
+**Configuring Client Credentials for Containers:**
+
+When deploying the sidecar in containerized environments (Kubernetes, AKS, Docker) with **Azure AD Workload Identity**, configure client credentials using environment variables:
+
+```yaml
+# Example Kubernetes deployment configuration
+env:
+  - name: AzureAd__Instance
+    value: "https://login.microsoftonline.com/"
+  - name: AzureAd__TenantId
+    value: "<tenant-guid>"
+  - name: AzureAd__ClientId
+    value: "<sidecar-client-id>"
+  - name: AzureAd__ClientCredentials__0__SourceType
+    value: "SignedAssertionFilePath"
+  - name: AzureAd__ClientCredentials__0__SignedAssertionFilePath
+    value: "/var/run/secrets/azure/tokens/azure-identity-token"
+```
+
+For **classic managed identity scenarios** (VMs, App Services), use:
+
+```yaml
+env:
+  - name: AzureAd__ClientCredentials__0__SourceType
+    value: "SignedAssertionFromManagedIdentity"
+  - name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
+    value: "<managed-identity-client-id>"  # Omit for system-assigned
+```
+
+For all credential configuration options, see the [CredentialDescription documentation](https://aka.ms/ms-id-web/credential-description).
+
 ## HTTP surface
 
 | Endpoint                                        | Method | Auth     | Description                                                                                      |