Extend MinimalPermissionsGuidancePlugin to support delegated and application permissions (#1423)

* Add SchemeName optional parameter to MinimalPermissionsGuidancePlugin

* Evaluate minimal permissions based on scheme name

* Extend report to specify scheme name if defined

* Update logging with scheme name if defined

---------

Co-authored-by: Waldek Mastykarz <[email protected]>

Author: bartizan

DevProxy.Plugins/Reporting/MinimalPermissionsGuidancePlugin.cs

@@ -17,6 +17,7 @@ public sealed class MinimalPermissionsGuidancePluginConfiguration
 {
     public string? ApiSpecsFolderPath { get; set; }
     public IEnumerable<string>? PermissionsToExclude { get; set; }
+    public string? SchemeName { get; set; }
 }
 
 public sealed class MinimalPermissionsGuidancePlugin(
@@ -83,7 +84,7 @@ public override async Task AfterRecordingStopAsync(RecordingArgs e, Cancellation
 
         foreach (var (apiSpec, requests) in requestsByApiSpec)
         {
-            var minimalPermissions = apiSpec.CheckMinimalPermissions(requests, Logger);
+            var minimalPermissions = apiSpec.CheckMinimalPermissions(requests, Logger, Configuration.SchemeName);
 
             IEnumerable<string> excessivePermissions = [.. minimalPermissions.TokenPermissions
                 .Except(Configuration.PermissionsToExclude ?? [])
@@ -100,7 +101,8 @@ public override async Task AfterRecordingStopAsync(RecordingArgs e, Cancellation
                 TokenPermissions = [.. minimalPermissions.TokenPermissions.Distinct()],
                 MinimalPermissions = minimalPermissions.MinimalScopes,
                 ExcessivePermissions = excessivePermissions,
-                UsesMinimalPermissions = !excessivePermissions.Any()
+                UsesMinimalPermissions = !excessivePermissions.Any(),
+                SchemeName = Configuration.SchemeName
             };
             results.Add(result);
 
@@ -112,20 +114,45 @@ public override async Task AfterRecordingStopAsync(RecordingArgs e, Cancellation
 
             if (result.UsesMinimalPermissions)
             {
-                Logger.LogInformation(
-                    "API {ApiName} is called with minimal permissions: {MinimalPermissions}",
-                    result.ApiName,
-                    string.Join(", ", result.MinimalPermissions)
-                );
+                if (string.IsNullOrWhiteSpace(Configuration.SchemeName))
+                {
+                    Logger.LogInformation(
+                        "API {ApiName} is called with minimal permissions: {MinimalPermissions}",
+                        result.ApiName,
+                        string.Join(", ", result.MinimalPermissions)
+                    );
+                }
+                else
+                {
+                    Logger.LogInformation(
+                        "API {ApiName} is called with minimal permissions of '{SchemeName}' scheme: {MinimalPermissions}",
+                        result.ApiName,
+                        Configuration.SchemeName,
+                        string.Join(", ", result.MinimalPermissions)
+                    );
+                }
             }
             else
             {
-                Logger.LogWarning(
-                    "Calling API {ApiName} with excessive permissions: {ExcessivePermissions}. Minimal permissions are: {MinimalPermissions}",
-                    result.ApiName,
-                    string.Join(", ", result.ExcessivePermissions),
-                    string.Join(", ", result.MinimalPermissions)
-                );
+                if (string.IsNullOrWhiteSpace(Configuration.SchemeName))
+                {
+                    Logger.LogWarning(
+                        "Calling API {ApiName} with excessive permissions: {ExcessivePermissions}. Minimal permissions are: {MinimalPermissions}",
+                        result.ApiName,
+                        string.Join(", ", result.ExcessivePermissions),
+                        string.Join(", ", result.MinimalPermissions)
+                    );
+                }
+                else
+                {
+                    Logger.LogWarning(
+                        "Calling API {ApiName} with excessive permissions of '{SchemeName}' scheme: {ExcessivePermissions}. Minimal permissions are: {MinimalPermissions}",
+                        result.ApiName,
+                        Configuration.SchemeName,
+                        string.Join(", ", result.ExcessivePermissions),
+                        string.Join(", ", result.MinimalPermissions)
+                    );
+                }
             }
 
             if (unmatchedApiRequests.Any())

DevProxy.Plugins/Reporting/MinimalPermissionsGuidancePluginReport.cs

@@ -17,6 +17,7 @@ public sealed class MinimalPermissionsGuidancePluginReportApiResult
     public required IEnumerable<string> Requests { get; init; }
     public required IEnumerable<string> TokenPermissions { get; init; }
     public required bool UsesMinimalPermissions { get; init; }
+    public string? SchemeName { get; init; }
 }
 
 public sealed class MinimalPermissionsGuidancePluginReport : IMarkdownReport, IPlainTextReport
@@ -39,14 +40,17 @@ public sealed class MinimalPermissionsGuidancePluginReport : IMarkdownReport, IP
 
         foreach (var result in Results)
         {
+            var permissionsHeader = "### Minimal permissions" + (string.IsNullOrWhiteSpace(result.SchemeName)
+                ? "" : $" for {result.SchemeName} scheme");
+
             _ = sb.AppendLine(CultureInfo.InvariantCulture, $"## API: {result.ApiName}")
                 .AppendLine()
                 .AppendLine("### Requests")
                 .AppendLine()
                 .AppendJoin(Environment.NewLine, result.Requests.Select(r => $"- {r}"))
                 .AppendLine()
                 .AppendLine()
-                .AppendLine("### Minimal permissions")
+                .AppendLine(permissionsHeader)
                 .AppendLine()
                 .AppendJoin(Environment.NewLine, result.MinimalPermissions.Select(p => $"- `{p}`"))
                 .AppendLine()
@@ -120,6 +124,8 @@ public sealed class MinimalPermissionsGuidancePluginReport : IMarkdownReport, IP
         foreach (var result in Results)
         {
             var apiTitle = $"API: {result.ApiName}";
+            var permissionsHeader = "Minimal permissions" + (string.IsNullOrWhiteSpace(result.SchemeName)
+                ? "" : $" for {result.SchemeName} scheme") + ":";
             _ = sb.AppendLine()
                 .AppendLine(apiTitle)
                 .AppendLine(new string('-', apiTitle.Length))
@@ -129,7 +135,7 @@ public sealed class MinimalPermissionsGuidancePluginReport : IMarkdownReport, IP
                 .AppendJoin(Environment.NewLine, result.Requests.Select(r => $"- {r}")).AppendLine()
                 .AppendLine();
 
-            _ = sb.AppendLine("Minimal permissions:")
+            _ = sb.AppendLine(permissionsHeader)
                 .AppendJoin(", ", result.MinimalPermissions).AppendLine()
                 .AppendLine();
 

schemas/v1.3.0/minimalpermissionsguidanceplugin.schema.json

@@ -18,6 +18,10 @@
       },
       "description": "The scopes to ignore and not include in the report. Default: ['profile', 'openid', 'offline_access', 'email'].",
       "default": ["profile", "openid", "offline_access", "email"]
+    },
+    "schemeName": {
+      "type": "string",
+      "description": "The name of the security scheme definition. Used to determine minimal permissions required for API calls."
     }
   },
   "required": [