[IDP-873] Generate Openapi Description of Security Requirements

README.md

@@ -165,8 +165,7 @@ Next, register the authorization services which all the required authorization p
 
 ```csharp
 builder.Services
-    .AddClientCredentialsAuthorization()
-    ;
+    .AddClientCredentialsAuthorization();
 ```
 
 Finally, register the authentication and authorization middlewares in your ASP.NET Core app and decorate your endpoints with the `AuthorizeAttribute`:

src/Workleap.AspNetCore.Authentication.ClientCredentialsGrant/AuthenticationBuilderExtensions.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Options;
+using Workleap.AspNetCore.Authentication.ClientCredentialsGrant.OpenAPI;
 
 // ReSharper disable once CheckNamespace
 namespace Microsoft.Extensions.DependencyInjection;
@@ -42,6 +43,19 @@ public static AuthenticationBuilder AddClientCredentials(this AuthenticationBuil
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<JwtBearerOptions>>(new JwtBearerOptionsValidator(authScheme)));
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<JwtBearerOptions>>(new ClientCredentialsPostConfigureOptions(authScheme)));
         }
+
+        builder.Services.ConfigureSwaggerGen(options =>
+        {
+            if (options.OperationFilterDescriptors.All(x => x.Type != typeof(SecurityRequirementOperationFilter)))
+            {
+                options.OperationFilter<SecurityRequirementOperationFilter>();
+            }
+
+            if (options.OperationFilterDescriptors.All(x => x.Type != typeof(SecurityDefinitionDocumentFilter)))
+            {
+                options.DocumentFilter<SecurityDefinitionDocumentFilter>();
+            }
+        });
 
         return builder;
     }

src/Workleap.AspNetCore.Authentication.ClientCredentialsGrant/ClientCredentialsDefaults.cs

@@ -13,4 +13,6 @@ public static class ClientCredentialsDefaults
     internal const string AuthorizationWritePolicy = "ClientCredentialsWrite";
 
     internal const string AuthorizationAdminPolicy = "ClientCredentialsAdmin";
+
+    internal static readonly string OpenApiSecurityDefinitionId = $"oauth2-{AuthenticationScheme.ToLowerInvariant()}";
 }

src/Workleap.AspNetCore.Authentication.ClientCredentialsGrant/OpenAPI/SecurityDefinitionDocumentFilter.cs

@@ -0,0 +1,59 @@
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Workleap.AspNetCore.Authentication.ClientCredentialsGrant.OpenAPI;
+
+internal sealed class SecurityDefinitionDocumentFilter : IDocumentFilter
+{
+    private readonly JwtBearerOptions _jwtOptions;
+
+    public SecurityDefinitionDocumentFilter(IOptionsMonitor<JwtBearerOptions> jwtOptionsMonitor)
+    {
+        this._jwtOptions = jwtOptionsMonitor.Get(ClientCredentialsDefaults.AuthenticationScheme);
+    }
+
+    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
+    {
+        var apiPermissions = context.ApiDescriptions.SelectMany(SwaggerUtils.GetRequiredPermissions).Distinct();
+
+        swaggerDoc.Components.SecuritySchemes.Add(
+            ClientCredentialsDefaults.OpenApiSecurityDefinitionId, 
+            new OpenApiSecurityScheme
+            {
+                Type = SecuritySchemeType.OAuth2,
+                Flows = new OpenApiOAuthFlows
+                {
+                    ClientCredentials = new OpenApiOAuthFlow
+                    {
+                        TokenUrl = this.GetTokenUrl(),
+                        Scopes = this.ExtractScopes(apiPermissions),
+                    },
+                },
+            });
+    }
+
+    private Uri GetTokenUrl()
+    {
+        var authority = this._jwtOptions.Authority?.TrimEnd('/') ?? string.Empty;
+        return new Uri($"{authority}/oauth2/token");
+    }
+
+    private Dictionary<string, string> ExtractScopes(IEnumerable<string> permissions)
+    {
+        var audience = this._jwtOptions.Audience ?? string.Empty;
+
+        var scopes = new Dictionary<string, string>
+        {
+            { SwaggerUtils.GetAllScope(audience), "Request all permissions for specified client_id" },
+        };
+
+        foreach (var permission in permissions)
+        {
+            scopes[SwaggerUtils.FormatScope(audience, $"Request this permission {permission} for specified client_id")] = permission;
+        }
+
+        return scopes;
+    }
+}

src/Workleap.AspNetCore.Authentication.ClientCredentialsGrant/OpenAPI/SecurityRequirementOperationFilter.cs

@@ -0,0 +1,94 @@
+using System.Globalization;
+using System.Text;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.WebUtilities;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Workleap.AspNetCore.Authentication.ClientCredentialsGrant.OpenAPI;
+
+internal sealed class SecurityRequirementOperationFilter : IOperationFilter
+{
+    private readonly JwtBearerOptions _jwtOptions;
+
+    public SecurityRequirementOperationFilter(IOptionsMonitor<JwtBearerOptions> jwtOptionsMonitor)
+    {
+        this._jwtOptions = jwtOptionsMonitor.Get(ClientCredentialsDefaults.AuthenticationScheme);
+    }
+
+    public void Apply(OpenApiOperation operation, OperationFilterContext context)
+    {
+        var attributes = SwaggerUtils.GetRequiredPermissions(context.ApiDescription).ToArray();
+        if (attributes.Length == 0)
+        {
+            return;
+        }
+
+        // Method need to be idempotent since minimal api are preserving the state
+        AddAuthzErrorResponse(operation);
+        this.AddOperationSecurityReference(operation, attributes);
+        AppendScopeToOperationSummary(operation, attributes);
+    }
+
+    private static void AddAuthzErrorResponse(OpenApiOperation operation)
+    {
+        operation.Responses.TryAdd(StatusCodes.Status401Unauthorized.ToString(CultureInfo.InvariantCulture), new OpenApiResponse { Description = ReasonPhrases.GetReasonPhrase(StatusCodes.Status401Unauthorized) });
+        operation.Responses.TryAdd(StatusCodes.Status403Forbidden.ToString(CultureInfo.InvariantCulture), new OpenApiResponse { Description = ReasonPhrases.GetReasonPhrase(StatusCodes.Status403Forbidden) });
+    }
+
+    private void AddOperationSecurityReference(OpenApiOperation operation, string[] permissions)
+    {
+        if (operation.Security.Any(requirement => requirement.Keys.Any(key => key.Reference?.Id == ClientCredentialsDefaults.OpenApiSecurityDefinitionId)))
+        {
+            return;
+        }
+
+        var securityScheme = new OpenApiSecurityScheme
+        {
+            Reference = new OpenApiReference
+            {
+                Type = ReferenceType.SecurityScheme,
+                Id = ClientCredentialsDefaults.OpenApiSecurityDefinitionId,
+            },
+        };
+
+        operation.Security.Add(new OpenApiSecurityRequirement
+        {
+            [securityScheme] = this.ExtractScopes(permissions).ToList(),
+        });
+    }
+
+    private static void AppendScopeToOperationSummary(OpenApiOperation operation, string[] scopes)
+    {
+        var requireScopeSummary = new StringBuilder();
+        requireScopeSummary.Append(scopes.Length == 1 ? "Required scope: " : "Required scopes: ");
+        requireScopeSummary.Append(string.Join(", ", scopes));
+        requireScopeSummary.Append('.');
+
+        var isRequireScopeSummaryPresent = operation.Summary?.Contains(requireScopeSummary.ToString()) ?? false;
+        if (isRequireScopeSummaryPresent)
+        {
+            return;
+        }
+
+        var summary = new StringBuilder(operation.Summary?.TrimEnd('.'));
+        if (summary.Length > 0)
+        {
+            summary.Append(". ");
+        }
+
+        summary.Append(requireScopeSummary);
+
+        operation.Summary = summary.ToString();
+    }
+
+    private IEnumerable<string> ExtractScopes(string[] permissions)
+    {
+        foreach (var permission in permissions)
+        {
+            yield return $"target-entity:{this._jwtOptions.Audience}:{permission}";
+        }
+    }
+}

src/Workleap.AspNetCore.Authentication.ClientCredentialsGrant/OpenAPI/SwaggerUtils.cs

@@ -0,0 +1,45 @@
+using System.Reflection;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Workleap.AspNetCore.Authentication.ClientCredentialsGrant.OpenAPI;
+
+internal static class SwaggerUtils
+{
+    public static IEnumerable<string> GetRequiredPermissions(ApiDescription apiDescription)
+    {
+        List<RequireClientCredentialsAttribute> attributes = new();
+
+        if (apiDescription.TryGetMethodInfo(out var methodInfo))
+        {
+            // Controllers - Attributes on the action method (empty for minimal APIs)
+            var methodAttributes = methodInfo.GetCustomAttributes<RequireClientCredentialsAttribute>(inherit: true).ToList();
+
+            if (methodAttributes.Count != 0)
+            {
+                attributes.AddRange(methodAttributes);
+            }
+            else if (methodInfo.DeclaringType != null)
+            {
+                // Controllers - Attributes on the controller class itself if was not overridden by the action method
+                attributes.AddRange(methodInfo.DeclaringType.GetCustomAttributes<RequireClientCredentialsAttribute>(inherit: true));
+            }
+        }
+
+        // Minimal APIs endpoint metadata (empty for controller actions)
+        attributes.AddRange(apiDescription.ActionDescriptor.EndpointMetadata.OfType<RequireClientCredentialsAttribute>());
+
+        return attributes.SelectMany(attribute => attribute.RequiredPermissions).Distinct();
+    }
+
+    // It assumes the identity provider is supporting the target-entity scope format
+    public static string FormatScope(string audience, string permission)
+    {
+        return $"target-entity:{audience}:{permission}";
+    }
+
+    public static string GetAllScope(string audience)
+    {
+        return $"target-entity:{audience}";
+    }
+}

src/Workleap.AspNetCore.Authentication.ClientCredentialsGrant/Workleap.AspNetCore.Authentication.ClientCredentialsGrant.csproj

@@ -14,6 +14,7 @@
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="6.0.0" Condition=" '$(TargetFramework)' == 'net6.0' " />
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="7.0.0" Condition=" '$(TargetFramework)' == 'net7.0' " />
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.0" Condition=" '$(TargetFramework)' == 'net8.0' " />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
     <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.3.4">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

src/Workleap.Authentication.ClientCredentialsGrant.Tests/OpenAPI/OpenApiSecurityDescriptionTests.cs

@@ -0,0 +1,46 @@
+using CliWrap;
+
+namespace Workleap.Authentication.ClientCredentialsGrant.Tests.OpenAPI;
+
+public class OpenApiSecurityDescriptionTests
+{
+    [Fact(Skip = "Test if fix build")]
+    public async Task Given_API_With_Client_Credential_Attribute_When_Generating_OpenAPI_Then_Equal_Expected_Document()
+    {
+        var solutionPath = GetSolutionPath();
+
+        var testsFolder = Path.Combine(solutionPath, "tests");
+        var projectFolder = Path.Combine(testsFolder, "WebApi.OpenAPI.SystemTest");
+        var generatedFilePath = Path.Combine(projectFolder, "openapi-v1.yaml");
+        var expectedFilePath = Path.Combine(testsFolder, "expected-openapi-document.yaml");
+
+        // Compile the project
+        var result = await Cli.Wrap("dotnet")
+            .WithWorkingDirectory(projectFolder)
+            .WithValidation(CommandResultValidation.None)
+            .WithArguments(a => a
+                .Add("build")
+                .Add("--no-incremental"))
+            .ExecuteAsync();
+
+        // Check if the build was successful
+        Assert.Equal(0, result.ExitCode);
+
+        // Compare the generated file with the expected file
+        var expectedFileContent = await File.ReadAllTextAsync(expectedFilePath);
+        var generatedFileContent = await File.ReadAllTextAsync(generatedFilePath);
+
+        Assert.Equal(expectedFileContent, generatedFileContent);
+    }
+
+    // TODO: Make this pretty
+    private static string GetSolutionPath()
+    {
+        var assemblyLocation = System.Reflection.Assembly.GetExecutingAssembly().Location;
+        var assemblyDirectory = Path.GetDirectoryName(assemblyLocation);
+
+        var solutionDirectory = Directory.GetParent(assemblyDirectory!)!.Parent!.Parent!.Parent!.FullName;
+
+        return solutionDirectory;
+    }
+}

src/Workleap.Authentication.ClientCredentialsGrant.Tests/Workleap.Authentication.ClientCredentialsGrant.Tests.csproj

@@ -14,6 +14,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="CliWrap" Version="3.6.6" />
     <PackageReference Include="Duende.IdentityServer" Version="6.3.9" />
     <PackageReference Include="FakeItEasy" Version="8.2.0" />
     <PackageReference Include="Microsoft.AspNetCore.TestHost" Version="6.0.0" Condition=" '$(TargetFramework)' == 'net6.0' " />

src/Workleap.Authentication.ClientCredentialsGrant.sln

@@ -16,6 +16,13 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Workleap.Authentication.Cli
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Workleap.AspNetCore.Authentication.ClientCredentialsGrant", "Workleap.AspNetCore.Authentication.ClientCredentialsGrant\Workleap.AspNetCore.Authentication.ClientCredentialsGrant.csproj", "{67B0A8F4-3292-4F39-923F-35814ADF4FA5}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebApi.OpenAPI.SystemTest", "tests\WebApi.OpenAPI.SystemTest\WebApi.OpenAPI.SystemTest.csproj", "{9667A3D7-4927-4CA1-B645-14898A687E30}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{75AE09A3-B3BD-4909-ADE7-CCF55EF71002}"
+	ProjectSection(SolutionItems) = preProject
+		tests\expected-openapi-document.yaml = tests\expected-openapi-document.yaml
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -37,5 +44,12 @@ Global
 		{67B0A8F4-3292-4F39-923F-35814ADF4FA5}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{67B0A8F4-3292-4F39-923F-35814ADF4FA5}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{67B0A8F4-3292-4F39-923F-35814ADF4FA5}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9667A3D7-4927-4CA1-B645-14898A687E30}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9667A3D7-4927-4CA1-B645-14898A687E30}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9667A3D7-4927-4CA1-B645-14898A687E30}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9667A3D7-4927-4CA1-B645-14898A687E30}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{9667A3D7-4927-4CA1-B645-14898A687E30} = {75AE09A3-B3BD-4909-ADE7-CCF55EF71002}
 	EndGlobalSection
 EndGlobal

src/tests/WebApi.OpenAPI.SystemTest/Program.cs

@@ -0,0 +1,23 @@
+using WebApi.OpenAPI.SystemTest;
+using WebApi.OpenAPI.SystemTest.SecurityRequirement;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddControllers();
+
+builder.Services.AddSwagger();
+
+// Setup specific to Client Credentials Grant
+builder.Services.AddAuthentication().AddClientCredentials();
+builder.Services.AddClientCredentialsAuthorization();
+
+var app = builder.Build();
+
+app.AddMinimalEndpoint();
+
+app.UseSwagger();
+app.UseSwaggerUI();
+
+app.MapControllers();
+
+app.Run();

src/tests/WebApi.OpenAPI.SystemTest/Properties/launchSettings.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7219;http://localhost:5241",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

src/tests/WebApi.OpenAPI.SystemTest/SecurityRequirement/ClientCredentialMinimalApis.cs

@@ -0,0 +1,14 @@
+using Workleap.AspNetCore.Authentication.ClientCredentialsGrant;
+
+namespace WebApi.OpenAPI.SystemTest.SecurityRequirement;
+
+public static class ClientCredentialMinimalApis
+{
+    public static void AddMinimalEndpoint(this WebApplication app)
+    {
+        app.MapGet("minimal-api", () => "Hello World")
+            .RequirePermission("cocktail.make")
+            .WithTags("ClientCredentials")
+            .WithOpenApi();
+    }
+}