Add HTTP Strict Transport Security (HSTS) model settings (#19333)

Author: MikeAlhayek

AGENTS.md

@@ -243,6 +243,13 @@ The project uses:
 - `AnalysisLevel` set to `latest-Recommended`
 - Specific CA rules are suppressed (see `Directory.Build.props`)
 
+### Documentation
+
+- Update the canonical page under `src\docs` whenever a change affects user-facing behavior, configuration, setup, public APIs, stereotypes, or extension points.
+- Add or update XML `<summary>` documentation for new or modified public interfaces, domain models, enums, and other public members that are part of the change.
+- Document each enum member individually when its behavior is relevant to users or downstream developers.
+- When XML documentation already exists, revise the existing block in place and keep `<param>` tags accurate and in signature order.
+
 ## Database Patterns
 
 ### YesSql Usage

src/OrchardCore.Modules/OrchardCore.Https/Drivers/HttpsSettingsDisplayDriver.cs

@@ -55,10 +55,10 @@ public override async Task<IDisplayResult> EditAsync(ISite site, HttpsSettings s
 
             if (!isHttpsRequest)
             {
-                await _notifier.WarningAsync(H["For safety, Enabling require HTTPS over HTTP has been prevented."]);
+                await _notifier.WarningAsync(H["For safety, changing HTTPS-only settings over HTTP has been prevented."]);
             }
 
-            model.EnableStrictTransportSecurity = settings.EnableStrictTransportSecurity;
+            model.StrictTransportSecurityMode = settings.StrictTransportSecurityMode;
             model.IsHttpsRequest = isHttpsRequest;
             model.RequireHttps = settings.RequireHttps;
             model.RequireHttpsPermanent = settings.RequireHttpsPermanent;
@@ -82,7 +82,12 @@ public override async Task<IDisplayResult> UpdateAsync(ISite site, HttpsSettings
 
         await context.Updater.TryUpdateModelAsync(model, Prefix);
 
-        settings.EnableStrictTransportSecurity = model.EnableStrictTransportSecurity;
+        if (!_httpContextAccessor.HttpContext.Request.IsHttps)
+        {
+            return await EditAsync(site, settings, context);
+        }
+
+        settings.StrictTransportSecurityMode = model.StrictTransportSecurityMode;
         settings.RequireHttps = model.RequireHttps;
         settings.RequireHttpsPermanent = model.RequireHttpsPermanent;
         settings.SslPort = model.SslPort;

src/OrchardCore.Modules/OrchardCore.Https/Migrations/HttpsSettingsMigrations.cs

@@ -0,0 +1,52 @@
+using System.Text.Json.Nodes;
+using OrchardCore.Data.Migration;
+using OrchardCore.Https.Settings;
+using OrchardCore.Settings;
+
+namespace OrchardCore.Https.Migrations;
+
+internal sealed class HttpsSettingsMigrations : DataMigration
+{
+    private readonly ISiteService _siteService;
+
+    public HttpsSettingsMigrations(ISiteService siteService)
+    {
+        _siteService = siteService;
+    }
+
+    [Obsolete]
+    public async Task<int> CreateAsync()
+    {
+        var site = await _siteService.LoadSiteSettingsAsync();
+
+        if (site.Properties[nameof(HttpsSettings)] is not JsonObject settingsObject)
+        {
+            return 1;
+        }
+
+        var requiresUpdate = false;
+
+        if (!settingsObject.ContainsKey(nameof(HttpsSettings.StrictTransportSecurityMode)) &&
+            settingsObject[nameof(HttpsSettings.EnableStrictTransportSecurity)] is JsonValue strictTransportSecurityValue &&
+            strictTransportSecurityValue.TryGetValue<bool>(out var enableStrictTransportSecurity))
+        {
+            settingsObject[nameof(HttpsSettings.StrictTransportSecurityMode)] = enableStrictTransportSecurity
+                ? nameof(HttpStrictTransportSecurityMode.Enabled)
+                : nameof(HttpStrictTransportSecurityMode.Disabled);
+
+            requiresUpdate = true;
+        }
+
+        if (settingsObject.Remove(nameof(HttpsSettings.EnableStrictTransportSecurity)))
+        {
+            requiresUpdate = true;
+        }
+
+        if (requiresUpdate)
+        {
+            await _siteService.UpdateSiteSettingsAsync(site);
+        }
+
+        return 1;
+    }
+}

src/OrchardCore.Modules/OrchardCore.Https/Settings/HttpStrictTransportSecurityMode.cs

@@ -0,0 +1,22 @@
+namespace OrchardCore.Https.Settings;
+
+/// <summary>
+/// Determines how HTTP Strict Transport Security (HSTS) is applied for the tenant.
+/// </summary>
+public enum HttpStrictTransportSecurityMode
+{
+    /// <summary>
+    /// Always disables HSTS regardless of the current environment.
+    /// </summary>
+    Disabled,
+
+    /// <summary>
+    /// Always enables HSTS regardless of the current environment.
+    /// </summary>
+    Enabled,
+
+    /// <summary>
+    /// Enables HSTS in the Production environment and disables it in other environments.
+    /// </summary>
+    FromConfiguration,
+}

src/OrchardCore.Modules/OrchardCore.Https/Settings/HttpsSettings.cs

@@ -1,9 +1,36 @@
+using System.Text.Json.Serialization;
+
 namespace OrchardCore.Https.Settings;
 
+/// <summary>
+/// Stores the HTTPS site settings for a tenant.
+/// </summary>
 public class HttpsSettings
 {
+    /// <summary>
+    /// Gets or sets the legacy HSTS toggle retained only so stored settings can be migrated to <see cref="StrictTransportSecurityMode"/>.
+    /// </summary>
+    [JsonIgnore]
+    [Obsolete("This property is obsolete and will be removed in future releases. Use StrictTransportSecurityMode instead.")]
     public bool EnableStrictTransportSecurity { get; set; }
+
+    /// <summary>
+    /// Gets or sets how HTTP Strict Transport Security (HSTS) is applied.
+    /// </summary>
+    public HttpStrictTransportSecurityMode StrictTransportSecurityMode { get; set; } = HttpStrictTransportSecurityMode.Disabled;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether all requests should be redirected to HTTPS.
+    /// </summary>
     public bool RequireHttps { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether HTTPS redirects should use a permanent redirect status code.
+    /// </summary>
     public bool RequireHttpsPermanent { get; set; }
+
+    /// <summary>
+    /// Gets or sets the HTTPS port to use for redirection when it cannot be inferred automatically.
+    /// </summary>
     public int? SslPort { get; set; }
 }

src/OrchardCore.Modules/OrchardCore.Https/Startup.cs

@@ -3,8 +3,11 @@
 using Microsoft.AspNetCore.HttpsPolicy;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using OrchardCore.Data.Migration;
 using OrchardCore.DisplayManagement.Handlers;
 using OrchardCore.Https.Drivers;
+using OrchardCore.Https.Migrations;
 using OrchardCore.Https.Services;
 using OrchardCore.Https.Settings;
 using OrchardCore.Modules;
@@ -25,7 +28,9 @@ public override async ValueTask ConfigureAsync(IApplicationBuilder app, IEndpoin
             app.UseHttpsRedirection();
         }
 
-        if (settings.EnableStrictTransportSecurity)
+        if (settings.StrictTransportSecurityMode == HttpStrictTransportSecurityMode.Enabled ||
+            (settings.StrictTransportSecurityMode == HttpStrictTransportSecurityMode.FromConfiguration &&
+             serviceProvider.GetRequiredService<IHostEnvironment>().IsProduction()))
         {
             app.UseHsts();
         }
@@ -36,6 +41,7 @@ public override void ConfigureServices(IServiceCollection services)
         services.AddSiteDisplayDriver<HttpsSettingsDisplayDriver>();
         services.AddNavigationProvider<AdminMenu>();
         services.AddSingleton<IHttpsService, HttpsService>();
+        services.AddDataMigration<HttpsSettingsMigrations>();
 
         services.AddPermissionProvider<Permissions>();
 

src/OrchardCore.Modules/OrchardCore.Https/ViewModels/HttpsSettingsViewModel.cs

@@ -1,9 +1,11 @@
+using OrchardCore.Https.Settings;
+
 namespace OrchardCore.Https.ViewModels;
 
 public class HttpsSettingsViewModel
 {
     public bool IsHttpsRequest { get; set; }
-    public bool EnableStrictTransportSecurity { get; set; }
+    public HttpStrictTransportSecurityMode StrictTransportSecurityMode { get; set; }
     public bool RequireHttps { get; set; }
     public bool RequireHttpsPermanent { get; set; }
     public int? SslPort { get; set; }

src/OrchardCore.Modules/OrchardCore.Https/Views/HttpsSettings.Edit.cshtml

@@ -10,19 +10,17 @@
     </div>
 </div>
 
-<div class="ocat-wrapper" asp-validation-class-for="EnableStrictTransportSecurity">
-    <div class="ocat-end-offset">
-        <div class="form-check">
-            <input type="checkbox" class="form-check-input" asp-for="EnableStrictTransportSecurity" asp-is-disabled="@(!Model.IsHttpsRequest)" />
-            <label class="form-check-label" asp-for="EnableStrictTransportSecurity">@T["Enable HSTS"]</label>
-            <span class="hint dashed">@T["Indicates to browsers that connecting without transport security (e.g SSL or TLS) isn't allowed."]</span>
-        </div>
-    </div>
-</div>
+<div class="ocat-wrapper" asp-validation-class-for="StrictTransportSecurityMode">
+    <label asp-for="StrictTransportSecurityMode" class="ocat-label">@T["HSTS mode"]</label>
+    <div class="ocat-end">
+        <select asp-for="StrictTransportSecurityMode" class="form-select" asp-is-disabled="@(!Model.IsHttpsRequest)">
+            <option value="@nameof(OrchardCore.Https.Settings.HttpStrictTransportSecurityMode.Disabled)">@T["Disabled"]</option>
+            <option value="@nameof(OrchardCore.Https.Settings.HttpStrictTransportSecurityMode.Enabled)">@T["Enabled"]</option>
+            <option value="@nameof(OrchardCore.Https.Settings.HttpStrictTransportSecurityMode.FromConfiguration)">@T["From environment — enabled in Production, disabled otherwise"]</option>
+        </select>
+        <span class="hint">@T["Determines whether HTTP Strict Transport Security (HSTS) headers are disabled by default, enabled explicitly, or follow the current environment."]</span>
+        <div class="alert alert-danger mt-3">@T["Use HSTS with caution, as browsers may stop connecting over HTTP after receiving the header if HTTPS later becomes unavailable."]</div>
 
-<div class="ocat-wrapper">
-    <div class="ocat-end-offset">
-        <div class="alert alert-danger">@T["This option should be enabled with caution, as it may prevent users from connecting if HTTPS was later disabled or wasn't available."]</div>
     </div>
 </div>
 

src/docs/reference/modules/Https/README.md

@@ -1,6 +1,6 @@
 # HTTPS (`OrchardCore.Https`)
 
-The module will ensure HTTPS is used when accessing the website. You can force HTTPS on all pages, enable HSTS, and configure the HTTPS port.
+The module will ensure HTTPS is used when accessing the website. You can force HTTPS on all pages, choose how HSTS is applied, and configure the HTTPS port.
 
 ## Recipe Configuration
 
@@ -12,7 +12,7 @@ HTTPS settings can be configured using the `Settings` recipe step:
     {
       "name": "settings",
       "HttpsSettings": {
-        "EnableStrictTransportSecurity": true,
+        "StrictTransportSecurityMode": "Disabled",
         "RequireHttps": true,
         "RequireHttpsPermanent": false,
         "SslPort": 443
@@ -22,9 +22,17 @@ HTTPS settings can be configured using the `Settings` recipe step:
 }
 ```
 
-| Property                        | Type    | Description                                                      |
-|---------------------------------|---------|------------------------------------------------------------------|
-| `EnableStrictTransportSecurity` | Boolean | Whether to enable HTTP Strict Transport Security (HSTS) headers. |
-| `RequireHttps`                  | Boolean | Whether to require HTTPS for all requests.                       |
-| `RequireHttpsPermanent`         | Boolean | Whether to use a permanent (301) redirect for HTTPS redirection. |
-| `SslPort`                       | Integer | The port number for SSL connections.                             |
+| Property                        | Type    | Description                                                                                  |
+|---------------------------------|---------|----------------------------------------------------------------------------------------------|
+| `StrictTransportSecurityMode`   | String  | Whether HTTP Strict Transport Security (HSTS) is `Disabled` by default, `Enabled`, or `FromConfiguration` (enabled in Production, disabled otherwise). |
+| `RequireHttps`                  | Boolean | Whether to require HTTPS for all requests.                                                   |
+| `RequireHttpsPermanent`         | Boolean | Whether to use a permanent (301) redirect for HTTPS redirection.                             |
+| `SslPort`                       | Integer | The port number for SSL connections.                                                         |
+
+### `StrictTransportSecurityMode` values
+
+| Value | Behavior |
+|-------|----------|
+| `Disabled` | Always disables HSTS headers, regardless of environment. |
+| `Enabled` | Always enables HSTS headers, regardless of environment. |
+| `FromConfiguration` | Enables HSTS automatically in the `Production` environment and disables it in other environments. |

test/OrchardCore.Tests/Modules/OrchardCore.Https/HttpsSettingsMigrationsTests.cs

@@ -0,0 +1,87 @@
+using System.Text.Json.Nodes;
+using Moq;
+using OrchardCore.Https.Settings;
+using OrchardCore.Settings;
+
+namespace OrchardCore.Tests.Modules.OrchardCore.Https;
+
+public class HttpsSettingsMigrationsTests
+{
+    private const string LegacyEnableStrictTransportSecurityKey = "EnableStrictTransportSecurity";
+
+    [Fact]
+    public async Task CreateAsyncMigratesLegacyHstsSetting()
+    {
+        var site = new SiteSettings();
+        site.Properties[nameof(HttpsSettings)] = new JsonObject
+        {
+            [LegacyEnableStrictTransportSecurityKey] = true,
+        };
+
+        var siteService = new Mock<ISiteService>();
+        siteService.Setup(service => service.LoadSiteSettingsAsync()).ReturnsAsync(site);
+        siteService.Setup(service => service.UpdateSiteSettingsAsync(site)).Returns(Task.CompletedTask);
+
+        var version = await InvokeCreateAsync(siteService.Object);
+
+        Assert.Equal(1, version);
+        Assert.Equal(
+            nameof(HttpStrictTransportSecurityMode.Enabled),
+            site.Properties[nameof(HttpsSettings)]?[nameof(HttpsSettings.StrictTransportSecurityMode)]?.GetValue<string>());
+        Assert.Null(site.Properties[nameof(HttpsSettings)]?[LegacyEnableStrictTransportSecurityKey]);
+        siteService.Verify(service => service.UpdateSiteSettingsAsync(site), Times.Once);
+    }
+
+    [Fact]
+    public async Task CreateAsyncRemovesLegacySettingWithoutOverwritingMigratedValue()
+    {
+        var site = new SiteSettings();
+        site.Properties[nameof(HttpsSettings)] = new JsonObject
+        {
+            [nameof(HttpsSettings.StrictTransportSecurityMode)] = nameof(HttpStrictTransportSecurityMode.Disabled),
+            [LegacyEnableStrictTransportSecurityKey] = true,
+        };
+
+        var siteService = new Mock<ISiteService>();
+        siteService.Setup(service => service.LoadSiteSettingsAsync()).ReturnsAsync(site);
+        siteService.Setup(service => service.UpdateSiteSettingsAsync(site)).Returns(Task.CompletedTask);
+
+        var version = await InvokeCreateAsync(siteService.Object);
+
+        Assert.Equal(1, version);
+        Assert.Equal(
+            nameof(HttpStrictTransportSecurityMode.Disabled),
+            site.Properties[nameof(HttpsSettings)]?[nameof(HttpsSettings.StrictTransportSecurityMode)]?.GetValue<string>());
+        Assert.Null(site.Properties[nameof(HttpsSettings)]?[LegacyEnableStrictTransportSecurityKey]);
+        siteService.Verify(service => service.UpdateSiteSettingsAsync(site), Times.Once);
+    }
+
+    private static async Task<int> InvokeCreateAsync(ISiteService siteService)
+    {
+        var migrationType = typeof(HttpsSettings).Assembly.GetType("OrchardCore.Https.Migrations.HttpsSettingsMigrations");
+        if (migrationType is null)
+        {
+            throw new InvalidOperationException("Unable to locate the HTTPS settings migration type.");
+        }
+
+        var migration = Activator.CreateInstance(migrationType, siteService);
+        if (migration is null)
+        {
+            throw new InvalidOperationException("Unable to create the HTTPS settings migration instance.");
+        }
+
+        var method = migrationType.GetMethod("CreateAsync");
+        if (method is null)
+        {
+            throw new InvalidOperationException("Unable to locate the HTTPS settings migration CreateAsync method.");
+        }
+
+        var result = method.Invoke(migration, null) as Task<int>;
+        if (result is null)
+        {
+            throw new InvalidOperationException("Unable to invoke the HTTPS settings migration CreateAsync method.");
+        }
+
+        return await result;
+    }
+}