Fixes #2899

Author: IEvangelist

docs/compatibility/9.2/index.md

@@ -20,3 +20,4 @@ If you're migrating an app to .NET Aspire 9.2, the breaking changes listed here
 |--|--|--|
 | [WithCommand obsolete and new overload with CommandOptions](withcommand-obsolete.md) | Source incompatible | 9.2 |
 | [With authentication API creates keyvault resource in the app model](withauthentication-changes.md) | Behavioral change | 9.2 |
+| [KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser](keyvault-role-assignment-changes.md) | Behavioral change | 9.2 |

docs/compatibility/9.2/keyvault-role-assignment-changes.md

@@ -0,0 +1,59 @@
+---
+title: "Breaking change - KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser"
+description: "Learn about the breaking change in .NET Aspire 9.2 where the default role for Azure KeyVault applications changes to KeyVaultSecretsUser."
+ms.date: 03/27/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/2899
+---
+
+# KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser
+
+In .NET Aspire 9.2, the default role assigned to applications referencing Azure KeyVault has changed from <xref:Azure.Provisioning.KeyVault.KeyVaultBuiltInRole.KeyVaultAdministrator> to <xref:Azure.Provisioning.KeyVault.KeyVaultBuiltInRole.KeyVaultSecretsUser>. This change enhances security by limiting default privileges to only reading secrets. Applications requiring higher privileges must explicitly configure them.
+
+## Version introduced
+
+.NET Aspire 9.2
+
+## Previous behavior
+
+Previously, applications referencing Azure KeyVault were automatically granted the `KeyVaultAdministrator` role, which allowed full management of KeyVault settings.
+
+## New behavior
+
+Applications referencing Azure KeyVault are now granted the `KeyVaultSecretsUser` role by default, which restricts access to reading secrets. If higher privileges are required, they can be configured using the `WithRoleAssignments` API.
+
+Example:
+
+```csharp
+using Azure.Provisioning.KeyVault;
+
+var kv = builder.AddAzureKeyVault("kv");
+
+builder.AddProject<Projects.ApiService>("api")
+       .WithRoleAssignments(kv, KeyVaultBuiltInRole.KeyVaultContributor);
+```
+
+## Type of breaking change
+
+This is a [behavioral change](../categories.md#behavioral-change).
+
+## Reason for change
+
+The `KeyVaultAdministrator` role provides excessive privileges for most applications, as they typically only need to read secrets. Assigning the `KeyVaultSecretsUser` role by default improves security by adhering to the principle of least privilege.
+
+## Recommended action
+
+If your application requires higher privileges than the `KeyVaultSecretsUser` role, explicitly configure the necessary roles using the `WithRoleAssignments` API. For example:
+
+```csharp
+using Azure.Provisioning.KeyVault;
+
+var kv = builder.AddAzureKeyVault("kv");
+
+builder.AddProject<Projects.ApiService>("api")
+       .WithRoleAssignments(kv, KeyVaultBuiltInRole.KeyVaultContributor);
+```
+
+## Affected APIs
+
+- <xref:Aspire.Hosting.AzureKeyVaultResourceExtensions.AddAzureKeyVault*>

docs/compatibility/9.2/withauthentication-changes.md

@@ -30,7 +30,7 @@ In .NET Aspire 9.2, calling `WithAccessKeyAuthentication` or `WithPasswordAuthen
 
 ## Type of breaking change
 
-This is a [behavioral change](../../categories.md#behavioral-change).
+This is a [behavioral change](../categories.md#behavioral-change).
 
 ## Reason for change
 

docs/compatibility/9.2/withcommand-obsolete.md

@@ -81,7 +81,7 @@ The only required parameters are the `name`, `displayName`, and `executeCommand`
 
 ## Type of breaking change
 
-This is a [source incompatible](../../categories.md#source-compatibility) change.
+This is a [source incompatible](../categories.md#source-compatibility) change.
 
 ## Reason for change
 

docs/compatibility/toc.yml

@@ -17,6 +17,8 @@ items:
       href: 9.2/withcommand-obsolete.md
     - name: With authentication APIs include semantic changes
       href: 9.2/withauthentication-changes.md
+    - name: KeyVault default role assignment changes
+      href: 9.2/keyvault-role-assignment-changes.md
 - name: .NET Aspire 9.1
   expanded: false
   items: