[IDP-873] Generate Openapi Description of Security Requirements

README.md

@@ -35,6 +35,7 @@ The **server-side library** includes:
 * JWT authentication using the [Microsoft.AspNetCore.Authentication.JwtBearer](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer) library.
 * Authorization attribute and policy to easily enforce granular scopes on your endpoints.
 * Authorization attribute and policy to easily enforce classic Workleap permissions (read, write, admin).
+* Support of OpenAPI Security Definition and Security Requirement generation when using Swashbuckle.
 * Non-intrusive: default policies must be explicitly used, and the default authentication scheme can be modified.
 * Support for ASP.NET Core 6.0 and later.
 
@@ -165,8 +166,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`:
@@ -187,6 +187,59 @@ app.MapGet("/hello-world", () => "Hello World!").RequireAuthorization("my-policy
 public IActionResult HelloWorld() => this.Ok("Hello world");
 ```
 
+#### OpenAPI integration
+
+If you are using Swashbuckle to generate your OpenAPI documentation, if you are using the  `RequireClientCredentials` attribute it will automatically populate the security definitions and requirements in the OpenAPI document.
+
+For example:
+
+```csharp
+
+// When using Controlled-Based
+[HttpGet]
+[Route("weather")]
+[RequireClientCredentials("read")]
+public async Task<IActionResult> GetWeather()
+{...}
+
+// When using Minimal APIs
+app.MapGet("/weather", () => {...}).RequirePermission("read");
+```
+
+Will generate this:
+
+```yaml
+paths:
+  /weather:
+    get:
+      summary: 'Required scope: read.'
+      responses:
+        '200':
+          description: OK
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden
+      security:
+        - oauth2-clientcredentials:
+            - target-entity:b108bbc9-538e-403b-9faf-e5cd874eb17f:read /* Based on ClientCredentials options: Audience */
+components:
+  securitySchemes:
+    oauth2-clientcredentials:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://localhost:9020/oauth2/token /* Based on ClientCredentials options: Authority */
+          scopes:
+            target-entity:b108bbc9-538e-403b-9faf-e5cd874eb17f: Request all permissions for specified client_id
+            target-entity:b108bbc9-538e-403b-9faf-e5cd874eb17f:Request this permission read for specified client_id: read
+
+
+```
+
+
+```csharp
+
 
 ## Building, releasing and versioning
 

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

@@ -4,6 +4,8 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Options;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using Workleap.AspNetCore.Authentication.ClientCredentialsGrant.OpenAPI;
 
 // ReSharper disable once CheckNamespace
 namespace Microsoft.Extensions.DependencyInjection;
@@ -19,6 +21,9 @@ public static AuthenticationBuilder AddClientCredentials(this AuthenticationBuil
     public static AuthenticationBuilder AddClientCredentials(this AuthenticationBuilder builder, Action<JwtBearerOptions> configureOptions)
         => builder.AddClientCredentials(ClientCredentialsDefaults.AuthenticationScheme, configureOptions);
 
+    /// <summary>
+    /// Adds the Client Credentials authentication scheme and register Swagger security definition and requirement generation.
+    /// </summary>
     public static AuthenticationBuilder AddClientCredentials(this AuthenticationBuilder builder, string authScheme, Action<JwtBearerOptions> configureOptions)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -43,6 +48,19 @@ public static AuthenticationBuilder AddClientCredentials(this AuthenticationBuil
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<JwtBearerOptions>>(new ClientCredentialsPostConfigureOptions(authScheme)));
         }
 
+        builder.Services.PostConfigure<SwaggerGenOptions>(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/AuthorizationExtensions.cs

@@ -16,6 +16,9 @@ public static class AuthorizationExtensions
         [ClientCredentialsScope.Admin] = "admin",
     };
 
+    /// <summary>
+    /// 
+    /// </summary>
     public static IServiceCollection AddClientCredentialsAuthorization(this IServiceCollection services)
     {
         ArgumentNullException.ThrowIfNull(services);

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,62 @@
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Workleap.AspNetCore.Authentication.ClientCredentialsGrant.OpenAPI;
+
+/// <summary>
+/// Extract all permissions defined on this API based on the <see cref="RequireClientCredentialsAttribute"/> attributes and set it as security definition in OpenAPI.
+/// </summary>
+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,97 @@
+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;
+
+/// <summary>
+/// Add client credential security requirement for each endpoints in OpenAPI based on the <see cref="RequireClientCredentialsAttribute"/> attributes.
+/// </summary>
+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,42 @@
+using System.Reflection;
+using Microsoft.AspNetCore.Authorization;
+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))
+        {
+            var hasAllowAnonymous = methodInfo.GetCustomAttributes<AllowAnonymousAttribute>(inherit: true).Any();
+            if (hasAllowAnonymous)
+            {
+                return Enumerable.Empty<string>();
+            }
+
+            // Controllers - Attributes on the action method (empty for minimal APIs)
+            attributes.AddRange(methodInfo.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/RequireClientCredentialsAttribute.cs

@@ -4,7 +4,7 @@
 
 namespace Workleap.AspNetCore.Authentication.ClientCredentialsGrant;
 
-[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
+[AttributeUsage(AttributeTargets.Method)]
 public sealed class RequireClientCredentialsAttribute : AuthorizeAttribute
 {
     private static readonly Dictionary<ClientCredentialsScope, string> EnumScopeNameMapping = new()

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

@@ -9,11 +9,16 @@
     <AssemblyOriginatorKeyFile>../Workleap.Authentication.ClientCredentialsGrant.snk</AssemblyOriginatorKeyFile>
     <Description>Server-side implementation of authenticated machine-to-machine communication using access token for ASP.NET Core.</Description>
   </PropertyGroup>
-
+
+  <PropertyGroup>
+    <OpenApiGenerateDocumentsOnBuild>false</OpenApiGenerateDocumentsOnBuild>
+  </PropertyGroup>
+
   <ItemGroup>
     <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>