Add OpenAPI security transformer and options classes

Introduce OpenApiSecurityDocumentTransformer for injecting OAuth2 and HTTP bearer security schemes into OpenAPI docs, with configurable global requirements. Add OpenApiSecurityOptions for flexible scheme and endpoint configuration. Both files include MIT license headers and XML docs.

Author: vp

src/Presentation.Web/OpenApi/OpenApiSecurityDocumentTransformer.cs

@@ -0,0 +1,128 @@
+// MIT-License
+// Copyright BridgingIT GmbH - All Rights Reserved
+// Use of this source code is governed by an MIT-style license that can be
+// found in the LICENSE file at https://github.com/bridgingit/bitdevkit/license
+
+namespace BridgingIT.DevKit.Presentation.Web.OpenApi;
+
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.OpenApi;
+
+/// <summary>
+/// Adds configurable OAuth2 and HTTP bearer security schemes to an OpenAPI document.
+/// </summary>
+/// <remarks>
+/// This transformer is OpenAPI-focused rather than Scalar-specific. It updates the generated
+/// document components and global security requirements so any OpenAPI consumer can understand
+/// the configured authentication model.
+/// </remarks>
+public sealed class OpenApiSecurityDocumentTransformer : IOpenApiDocumentTransformer
+{
+    /// <summary>
+    /// Applies the configured OpenAPI security schemes and global requirements to the document.
+    /// </summary>
+    /// <param name="document">The OpenAPI document being transformed.</param>
+    /// <param name="context">The transformation context, including access to application services.</param>
+    /// <param name="cancellationToken">A cancellation token for the operation.</param>
+    /// <returns>A completed task after the document has been updated.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when <see cref="OpenApiSecurityOptions"/> has not been registered in the DI container.
+    /// </exception>
+    /// <remarks>
+    /// The transformer can add:
+    /// <list type="bullet">
+    /// <item>A reusable OAuth2 authorization code security scheme.</item>
+    /// <item>A reusable HTTP bearer security scheme for JWT tokens.</item>
+    /// <item>Global OpenAPI security requirements that reference one or both schemes.</item>
+    /// </list>
+    /// </remarks>
+    public Task TransformAsync(
+        OpenApiDocument document,
+        OpenApiDocumentTransformerContext context,
+        CancellationToken cancellationToken)
+    {
+        var optionsAccessor = context.ApplicationServices
+            .GetService<Microsoft.Extensions.Options.IOptions<OpenApiSecurityOptions>>();
+
+        if (optionsAccessor is null)
+        {
+            throw new InvalidOperationException(
+                $"{nameof(OpenApiSecurityDocumentTransformer)} requires {nameof(OpenApiSecurityOptions)} to be registered in the DI container. ");
+        }
+
+        var options = optionsAccessor.Value;
+
+        document.Components ??= new OpenApiComponents();
+        document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>(StringComparer.OrdinalIgnoreCase);
+        document.Components.SecuritySchemes.Remove(options.OAuth2SchemeName);
+        document.Components.SecuritySchemes.Remove(options.BearerSchemeName);
+
+        if (options.AddOAuth2AuthorizationCodeScheme &&
+            !string.IsNullOrWhiteSpace(options.AuthorizationUrl) &&
+            !string.IsNullOrWhiteSpace(options.TokenUrl))
+        {
+            document.Components.SecuritySchemes[options.OAuth2SchemeName] = new OpenApiSecurityScheme
+            {
+                Type = SecuritySchemeType.OAuth2,
+                Description = "Authenticate using the OAuth2 authorization code flow.",
+                Flows = new OpenApiOAuthFlows
+                {
+                    AuthorizationCode = new OpenApiOAuthFlow
+                    {
+                        AuthorizationUrl = new Uri(options.AuthorizationUrl),
+                        TokenUrl = new Uri(options.TokenUrl),
+                        Scopes = (options.Scopes ?? []).ToDictionary(
+                            scope => scope,
+                            scope => $"Request the {scope} scope.",
+                            StringComparer.OrdinalIgnoreCase),
+                    },
+                },
+            };
+        }
+
+        if (options.AddHttpBearerScheme)
+        {
+            document.Components.SecuritySchemes[options.BearerSchemeName] = new OpenApiSecurityScheme
+            {
+                Type = SecuritySchemeType.Http,
+                Scheme = "bearer",
+                BearerFormat = "JWT",
+                Description = "The JWT token in the format: Bearer {token}",
+            };
+        }
+
+        if (!options.AddGlobalSecurityRequirements)
+        {
+            return Task.CompletedTask;
+        }
+
+        document.Security =
+            [
+                .. (document.Security ?? [])
+                    .Where(requirement => !requirement.Keys.Any(scheme =>
+                        string.Equals(scheme.Reference?.Id, options.OAuth2SchemeName, StringComparison.OrdinalIgnoreCase) ||
+                        string.Equals(scheme.Reference?.Id, options.BearerSchemeName, StringComparison.OrdinalIgnoreCase))),
+            ];
+
+        if (options.AddOAuth2AuthorizationCodeScheme &&
+            !string.IsNullOrWhiteSpace(options.AuthorizationUrl) &&
+            !string.IsNullOrWhiteSpace(options.TokenUrl))
+        {
+            document.Security.Add(new OpenApiSecurityRequirement
+            {
+                [new OpenApiSecuritySchemeReference(options.OAuth2SchemeName, document)] = [.. (options.Scopes ?? [])],
+            });
+        }
+
+        if (options.AddHttpBearerScheme)
+        {
+            document.Security.Add(new OpenApiSecurityRequirement
+            {
+                [new OpenApiSecuritySchemeReference(options.BearerSchemeName, document)] = [],
+            });
+        }
+
+        return Task.CompletedTask;
+    }
+}

src/Presentation.Web/OpenApi/OpenApiSecurityOptions.cs

@@ -0,0 +1,87 @@
+// MIT-License
+// Copyright BridgingIT GmbH - All Rights Reserved
+// Use of this source code is governed by an MIT-style license that can be
+// found in the LICENSE file at https://github.com/bridgingit/bitdevkit/license
+
+namespace BridgingIT.DevKit.Presentation.Web.OpenApi;
+
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+
+/// <summary>
+/// Configures generated OpenAPI security schemes and related OAuth2 endpoint metadata.
+/// </summary>
+public class OpenApiSecurityOptions
+{
+    /// <summary>
+    /// Gets or sets the name of the HTTP bearer security scheme in the OpenAPI document.
+    /// </summary>
+    public string BearerSchemeName { get; set; } = JwtBearerDefaults.AuthenticationScheme;
+
+    /// <summary>
+    /// Gets or sets the name of the OAuth2 security scheme in the OpenAPI document.
+    /// </summary>
+    public string OAuth2SchemeName { get; set; } = "OAuth2";
+
+    /// <summary>
+    /// Gets or sets a value indicating whether a HTTP bearer security scheme should be added.
+    /// </summary>
+    public bool AddHttpBearerScheme { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether an OAuth2 authorization code security scheme should be added.
+    /// </summary>
+    public bool AddOAuth2AuthorizationCodeScheme { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether global OpenAPI security requirements should be added.
+    /// </summary>
+    public bool AddGlobalSecurityRequirements { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets the authority base URL used to build OAuth2 authorization and token endpoint URLs.
+    /// </summary>
+    public string Authority { get; set; }
+
+    /// <summary>
+    /// Gets or sets the relative authorization endpoint path appended to <see cref="Authority"/>.
+    /// </summary>
+    public string AuthorizationPath { get; set; } = "/api/_system/identity/connect/authorize";
+
+    /// <summary>
+    /// Gets or sets the relative token endpoint path appended to <see cref="Authority"/>.
+    /// </summary>
+    public string TokenPath { get; set; } = "/api/_system/identity/connect/token";
+
+    /// <summary>
+    /// Gets or sets the scopes exposed by the OAuth2 authorization code flow.
+    /// </summary>
+    public string[] Scopes { get; set; } = ["openid", "profile", "email", "roles"];
+
+    /// <summary>
+    /// Gets the full OAuth2 authorization endpoint URL derived from <see cref="Authority"/> and <see cref="AuthorizationPath"/>.
+    /// </summary>
+    public string AuthorizationUrl
+    {
+        get
+        {
+            var authority = this.Authority?.TrimEnd('/');
+            return string.IsNullOrWhiteSpace(authority)
+                ? null
+                : $"{authority}{this.AuthorizationPath}";
+        }
+    }
+
+    /// <summary>
+    /// Gets the full OAuth2 token endpoint URL derived from <see cref="Authority"/> and <see cref="TokenPath"/>.
+    /// </summary>
+    public string TokenUrl
+    {
+        get
+        {
+            var authority = this.Authority?.TrimEnd('/');
+            return string.IsNullOrWhiteSpace(authority)
+                ? null
+                : $"{authority}{this.TokenPath}";
+        }
+    }
+}