Backoffice Login: Move access/refresh tokens to secure cookies

.github/BUILD.md

@@ -37,7 +37,7 @@ In order to work with the Umbraco source code locally, first make sure you have
 
 ### Familiarizing yourself with the code
 
-Umbraco is a .NET application using C#. The solution is broken down into multiple projects.  There are several class libraries. The `Umbraco.Web.UI` project is the main project that hosts the back office and login screen. This is the project you will want to run to see your changes.
+Umbraco is a .NET application using C#. The solution is broken down into multiple projects. There are several class libraries. The `Umbraco.Web.UI` project is the main project that hosts the back office and login screen. This is the project you will want to run to see your changes.
 
 There are two web projects in the solution with client-side assets based on TypeScript, `Umbraco.Web.UI.Client` and `Umbraco.Web.UI.Login`.
 
@@ -73,13 +73,20 @@ Just be careful not to include this change in your PR.
 
 Conversely, if you are working on front-end only, you want to build the back-end once and then run it. Before you do so, update the configuration in `appSettings.json` to add the following under `Umbraco:Cms:Security`:
 
-```
+```json
 "BackOfficeHost": "http://localhost:5173",
 "AuthorizeCallbackPathName": "/oauth_complete",
 "AuthorizeCallbackLogoutPathName": "/logout",
-"AuthorizeCallbackErrorPathName": "/error"
+"AuthorizeCallbackErrorPathName": "/error",
+"BackOfficeTokenCookie": {
+  "Enabled": true,
+  "SameSite": "None"
+}
 ```
 
+> [!NOTE]
+> If you get stuck in a login loop, try clearing your browser cookies for localhost, and make sure that the `BackOfficeTokenCookie` settings are correct. Namely, that `SameSite` should be set to `None` when running the front-end server separately.
+
 Then run Umbraco from the command line.
 
 ```

.github/copilot-instructions.md

@@ -110,7 +110,11 @@ Use this for frontend-only development with hot module reloading:
    "BackOfficeHost": "http://localhost:5173",
    "AuthorizeCallbackPathName": "/oauth_complete",
    "AuthorizeCallbackLogoutPathName": "/logout",
-   "AuthorizeCallbackErrorPathName": "/error"
+   "AuthorizeCallbackErrorPathName": "/error",
+   "BackOfficeTokenCookie": {
+     "Enabled": true,
+     "SameSite": "None"
+   }
    ```
 2. Run backend: `cd src/Umbraco.Web.UI && dotnet run --no-build`
 3. Run frontend dev server: `cd src/Umbraco.Web.UI.Client && npm run dev:server`

.vscode/launch.json

@@ -105,7 +105,10 @@
         "UMBRACO__CMS__SECURITY__BACKOFFICEHOST": "http://localhost:5173",
         "UMBRACO__CMS__SECURITY__AUTHORIZECALLBACKPATHNAME": "/oauth_complete",
         "UMBRACO__CMS__SECURITY__AUTHORIZECALLBACKLOGOUTPATHNAME": "/logout",
-        "UMBRACO__CMS__SECURITY__AUTHORIZECALLBACKERRORPATHNAME": "/error"
+        "UMBRACO__CMS__SECURITY__AUTHORIZECALLBACKERRORPATHNAME": "/error",
+        "UMBRACO__CMS__SECURITY__KEEPUSERLOGGEDIN": "true",
+        "UMBRACO__CMS__SECURITY__BACKOFFICETOKENCOOKIE__ENABLED": "true",
+        "UMBRACO__CMS__SECURITY__BACKOFFICETOKENCOOKIE__SAMESITE": "None"
       },
       "sourceFileMap": {
         "/Views": "${workspaceFolder}/Umbraco.Web.UI/Views"

src/Umbraco.Cms.Api.Common/DependencyInjection/HideBackOfficeTokensHandler.cs

@@ -0,0 +1,187 @@
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.AspNetCore.DataProtection;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Options;
+using OpenIddict.Server;
+using OpenIddict.Validation;
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.Configuration.Models;
+using Umbraco.Cms.Core.Events;
+using Umbraco.Cms.Core.Notifications;
+using Umbraco.Cms.Web.Common.Security;
+using Umbraco.Extensions;
+
+namespace Umbraco.Cms.Api.Common.DependencyInjection;
+
+internal sealed class HideBackOfficeTokensHandler
+    : IOpenIddictServerHandler<OpenIddictServerEvents.ApplyTokenResponseContext>,
+        IOpenIddictServerHandler<OpenIddictServerEvents.ExtractTokenRequestContext>,
+        IOpenIddictValidationHandler<OpenIddictValidationEvents.ProcessAuthenticationContext>,
+        INotificationHandler<UserLogoutSuccessNotification>
+{
+    private const string RedactedTokenValue = "[redacted]";
+    private const string AccessTokenCookieKey = "__Host-umbAccessToken";
+    private const string RefreshTokenCookieKey = "__Host-umbRefreshToken";
+
+    private readonly IHttpContextAccessor _httpContextAccessor;
+    private readonly IDataProtectionProvider _dataProtectionProvider;
+    private readonly BackOfficeTokenCookieSettings _backOfficeTokenCookieSettings;
+    private readonly GlobalSettings _globalSettings;
+
+    public HideBackOfficeTokensHandler(
+        IHttpContextAccessor httpContextAccessor,
+        IDataProtectionProvider dataProtectionProvider,
+        IOptions<BackOfficeTokenCookieSettings> backOfficeTokenCookieSettings,
+        IOptions<GlobalSettings> globalSettings)
+    {
+        _httpContextAccessor = httpContextAccessor;
+        _dataProtectionProvider = dataProtectionProvider;
+        _backOfficeTokenCookieSettings = backOfficeTokenCookieSettings.Value;
+        _globalSettings = globalSettings.Value;
+    }
+
+    /// <summary>
+    /// This is invoked when tokens (access and refresh tokens) are issued to a client. For the back-office client,
+    /// we will intercept the response, write the tokens from the response into HTTP-only cookies, and redact the
+    /// tokens from the response, so they are not exposed to the client.
+    /// </summary>
+    public ValueTask HandleAsync(OpenIddictServerEvents.ApplyTokenResponseContext context)
+    {
+        if (context.Request?.ClientId is not Constants.OAuthClientIds.BackOffice)
+        {
+            // Only ever handle the back-office client.
+            return ValueTask.CompletedTask;
+        }
+
+        HttpContext httpContext = GetHttpContext();
+
+        if (context.Response.AccessToken is not null)
+        {
+            SetCookie(httpContext, AccessTokenCookieKey, context.Response.AccessToken);
+            context.Response.AccessToken = RedactedTokenValue;
+        }
+
+        if (context.Response.RefreshToken is not null)
+        {
+            SetCookie(httpContext, RefreshTokenCookieKey, context.Response.RefreshToken);
+            context.Response.RefreshToken = RedactedTokenValue;
+        }
+
+        return ValueTask.CompletedTask;
+    }
+
+    /// <summary>
+    /// This is invoked when requesting new tokens.
+    /// </summary>
+    public ValueTask HandleAsync(OpenIddictServerEvents.ExtractTokenRequestContext context)
+    {
+        if (context.Request?.ClientId != Constants.OAuthClientIds.BackOffice)
+        {
+            // Only ever handle the back-office client.
+            return ValueTask.CompletedTask;
+        }
+
+        // For the back-office client, this only happens when a refresh token is being exchanged for a new access token.
+        if (context.Request.RefreshToken == RedactedTokenValue
+            && TryGetCookie(RefreshTokenCookieKey, out var refreshToken))
+        {
+            context.Request.RefreshToken = refreshToken;
+        }
+        else
+        {
+            // If we got here, either the refresh token was not redacted, or nothing was found in the refresh token cookie.
+            // If OpenIddict found a refresh token, it could be an old token that is potentially still valid. For security
+            // reasons, we cannot accept that; at this point, we expect the refresh tokens to be explicitly redacted.
+            context.Request.RefreshToken = null;
+        }
+
+
+        return ValueTask.CompletedTask;
+    }
+
+    /// <summary>
+    /// This is invoked when extracting the auth context for a client request.
+    /// </summary>
+    public ValueTask HandleAsync(OpenIddictValidationEvents.ProcessAuthenticationContext context)
+    {
+        // For the back-office client, this only happens when an access token is sent to the API.
+        if (context.AccessToken != RedactedTokenValue)
+        {
+            return ValueTask.CompletedTask;
+        }
+
+        if (TryGetCookie(AccessTokenCookieKey, out var accessToken))
+        {
+            context.AccessToken = accessToken;
+        }
+
+        return ValueTask.CompletedTask;
+    }
+
+    public void Handle(UserLogoutSuccessNotification notification)
+    {
+        HttpContext? context = _httpContextAccessor.HttpContext;
+        if (context is null)
+        {
+            // For some reason there is no ambient HTTP context, so we can't clean up the cookies.
+            // This is OK, because the tokens in the cookies have already been revoked at user sign-out,
+            // so the cookie clean-up is mostly cosmetic.
+            return;
+        }
+
+        context.Response.Cookies.Delete(AccessTokenCookieKey);
+        context.Response.Cookies.Delete(RefreshTokenCookieKey);
+    }
+
+    private HttpContext GetHttpContext()
+        => _httpContextAccessor.GetRequiredHttpContext();
+
+    private void SetCookie(HttpContext httpContext, string key, string value)
+    {
+        var cookieValue = EncryptionHelper.Encrypt(value, _dataProtectionProvider);
+
+        var cookieOptions = new CookieOptions
+        {
+            // Prevent the client-side scripts from accessing the cookie.
+            HttpOnly = true,
+
+            // Mark the cookie as essential to the application, to enforce it despite any
+            // data collection consent options. This aligns with how ASP.NET Core Identity
+            // does when writing cookies for cookie authentication.
+            IsEssential = true,
+
+            // Cookie path must be root for optimal security.
+            Path = "/",
+
+            // For optimal security, the cooke must be secure. However, Umbraco allows for running development
+            // environments over HTTP, so we need to take that into account here.
+            // Thus, we will make the cookie secure if:
+            // - HTTPS is explicitly enabled by config (default for production environments), or
+            // - The current request is over HTTPS (meaning the environment supports it regardless of config).
+            Secure = _globalSettings.UseHttps || httpContext.Request.IsHttps,
+
+            // SameSite is configurable (see BackOfficeTokenCookieSettings for defaults):
+            SameSite = ParseSameSiteMode(_backOfficeTokenCookieSettings.SameSite),
+        };
+
+        httpContext.Response.Cookies.Delete(key, cookieOptions);
+        httpContext.Response.Cookies.Append(key, cookieValue, cookieOptions);
+    }
+
+    private bool TryGetCookie(string key, [NotNullWhen(true)] out string? value)
+    {
+        if (GetHttpContext().Request.Cookies.TryGetValue(key, out var cookieValue))
+        {
+            value = EncryptionHelper.Decrypt(cookieValue, _dataProtectionProvider);
+            return true;
+        }
+
+        value = null;
+        return false;
+    }
+
+    private static SameSiteMode ParseSameSiteMode(string sameSiteMode) =>
+        Enum.TryParse(sameSiteMode, ignoreCase: true, out SameSiteMode result)
+            ? result
+            : throw new ArgumentException($"The provided {nameof(sameSiteMode)} value could not be parsed into as SameSiteMode value.", nameof(sameSiteMode));
+}

src/Umbraco.Cms.Api.Common/DependencyInjection/UmbracoBuilderAuthExtensions.cs

@@ -9,6 +9,7 @@
 using Umbraco.Cms.Core;
 using Umbraco.Cms.Core.Configuration.Models;
 using Umbraco.Cms.Core.DependencyInjection;
+using Umbraco.Cms.Core.Notifications;
 using Umbraco.Cms.Infrastructure.BackgroundJobs.Jobs;
 using Umbraco.Extensions;
 
@@ -28,118 +29,155 @@
 
     private static void ConfigureOpenIddict(IUmbracoBuilder builder)
     {
+        // Optionally hide tokens from the back-office.
+        var hideBackOfficeTokens = (builder.Config
+            .GetSection(Constants.Configuration.ConfigBackOfficeTokenCookie)
+            .Get<BackOfficeTokenCookieSettings>() ?? new BackOfficeTokenCookieSettings()).Enabled;
+
         builder.Services.AddOpenIddict()
             // Register the OpenIddict server components.
             .AddServer(options =>
             {
                 // Enable the authorization and token endpoints.
                 // - important: member endpoints MUST be added before backoffice endpoints to ensure that auto-discovery works for members
                 options
                     .SetAuthorizationEndpointUris(
                         Paths.MemberApi.AuthorizationEndpoint.TrimStart(Constants.CharArrays.ForwardSlash),
                         Paths.BackOfficeApi.AuthorizationEndpoint.TrimStart(Constants.CharArrays.ForwardSlash))
                     .SetTokenEndpointUris(
                         Paths.MemberApi.TokenEndpoint.TrimStart(Constants.CharArrays.ForwardSlash),
                         Paths.BackOfficeApi.TokenEndpoint.TrimStart(Constants.CharArrays.ForwardSlash))
                     .SetEndSessionEndpointUris(
                         Paths.MemberApi.LogoutEndpoint.TrimStart(Constants.CharArrays.ForwardSlash),
                         Paths.BackOfficeApi.LogoutEndpoint.TrimStart(Constants.CharArrays.ForwardSlash))
                     .SetRevocationEndpointUris(
                         Paths.MemberApi.RevokeEndpoint.TrimStart(Constants.CharArrays.ForwardSlash),
                         Paths.BackOfficeApi.RevokeEndpoint.TrimStart(Constants.CharArrays.ForwardSlash))
                     .SetUserInfoEndpointUris(
                         Paths.MemberApi.UserinfoEndpoint.TrimStart(Constants.CharArrays.ForwardSlash));
 
                 // Enable authorization code flow with PKCE
                 options
                     .AllowAuthorizationCodeFlow()
                     .RequireProofKeyForCodeExchange()
                     .AllowRefreshTokenFlow();
 
                 // Enable the client credentials flow.
                 options.AllowClientCredentialsFlow();
 
                 // Register the ASP.NET Core host and configure for custom authentication endpoint.
                 options
                     .UseAspNetCore()
                     .EnableAuthorizationEndpointPassthrough()
                     .EnableTokenEndpointPassthrough()
                     .EnableEndSessionEndpointPassthrough()
                     .EnableUserInfoEndpointPassthrough();
 
                 // Enable reference tokens
                 // - see https://documentation.openiddict.com/configuration/token-storage.html
                 options
                     .UseReferenceAccessTokens()
                     .UseReferenceRefreshTokens();
 
                 // Apply sliding window expiry based on the configured max login lifetime
                 GlobalSettings globalSettings = builder.Config
                     .GetSection(Constants.Configuration.ConfigGlobal)
                     .Get<GlobalSettings>() ?? new GlobalSettings();
                 TimeSpan timeOut = globalSettings.TimeOut;
 
                 // Make the access token lifetime 25% of the refresh token lifetime, to help ensure that new access tokens
                 // are obtained by the client before the refresh token expires.
                 options.SetAccessTokenLifetime(new TimeSpan(timeOut.Ticks / 4));
                 options.SetRefreshTokenLifetime(timeOut);
 
                 // Use ASP.NET Core Data Protection for tokens instead of JWT.
                 // This is more secure, and has the added benefit of having a high throughput
                 // but means that all servers (such as in a load balanced setup)
                 // needs to use the same application name and key ring,
                 // however this is already recommended for load balancing, so should be fine.
                 // See https://documentation.openiddict.com/configuration/token-formats.html#switching-to-data-protection-tokens
                 // and https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-7.0
                 // for more information
                 options.UseDataProtection();
 
                 // Register encryption and signing credentials to protect tokens.
                 // Note that for tokens generated/validated using ASP.NET Core Data Protection,
                 // a separate key ring is used, distinct from the credentials discussed in
                 // https://documentation.openiddict.com/configuration/encryption-and-signing-credentials.html
                 // More details can be found here: https://github.com/openiddict/openiddict-core/issues/1892#issuecomment-1737308506
                 // "When using ASP.NET Core Data Protection to generate opaque tokens, the signing and encryption credentials
                 // registered via Add*Key/Certificate() are not used". But since OpenIddict requires the registration of such,
                 // we can generate random keys per instance without them taking effect.
                 // - see also https://github.com/openiddict/openiddict-core/issues/1231
                 options
                     .AddEncryptionKey(new SymmetricSecurityKey(RandomNumberGenerator.GetBytes(32))) // generate a cryptographically secure random 256-bits key
                     .AddSigningKey(new RsaSecurityKey(RSA.Create(keySizeInBits: 2048))); // generate RSA key with recommended size of 2048-bits
 
                 // Add custom handler for the "ProcessRequestContext" server event, to stop OpenIddict from handling
                 // every last request to the server (including front-end requests).
                 options.AddEventHandler<OpenIddictServerEvents.ProcessRequestContext>(configuration =>
                 {
                     configuration.UseSingletonHandler<ProcessRequestContextHandler>().SetOrder(OpenIddict.Server.AspNetCore.OpenIddictServerAspNetCoreHandlers.ResolveRequestUri.Descriptor.Order - 1);
                 });
+
+                if (hideBackOfficeTokens)
+                {
+                    options.AddEventHandler<OpenIddictServerEvents.ApplyTokenResponseContext>(configuration =>
+                    {
+                        configuration
+                            .UseSingletonHandler<HideBackOfficeTokensHandler>()
+                            .SetOrder(OpenIddict.Server.AspNetCore.OpenIddictServerAspNetCoreHandlers.ProcessJsonResponse<OpenIddictServerEvents.ApplyTokenResponseContext>.Descriptor.Order - 1);
+                    });
+                    options.AddEventHandler<OpenIddictServerEvents.ExtractTokenRequestContext>(configuration =>
+                    {
+                        configuration
+                            .UseSingletonHandler<HideBackOfficeTokensHandler>()
+                            .SetOrder(OpenIddict.Server.AspNetCore.OpenIddictServerAspNetCoreHandlers.ExtractPostRequest<OpenIddictServerEvents.ExtractTokenRequestContext>.Descriptor.Order + 1);
+                    });
+                }
             })
 
             // Register the OpenIddict validation components.
             .AddValidation(options =>
             {
                 // Import the configuration from the local OpenIddict server instance.
                 options.UseLocalServer();
 
                 // Register the ASP.NET Core host.
                 options.UseAspNetCore();
 
                 // Enable token entry validation
                 // - see https://documentation.openiddict.com/configuration/token-storage.html#enabling-token-entry-validation-at-the-api-level
                 options.EnableTokenEntryValidation();
 
                 // Use ASP.NET Core Data Protection for tokens instead of JWT. (see note in AddServer)
                 options.UseDataProtection();
 
                 // Add custom handler for the "ProcessRequestContext" validation event, to stop OpenIddict from handling
                 // every last request to the server (including front-end requests).
                 options.AddEventHandler<OpenIddictValidationEvents.ProcessRequestContext>(configuration =>
                 {
                     configuration.UseSingletonHandler<ProcessRequestContextHandler>().SetOrder(OpenIddict.Validation.AspNetCore.OpenIddictValidationAspNetCoreHandlers.ResolveRequestUri.Descriptor.Order - 1);
                 });
+
+                if (hideBackOfficeTokens)
+                {
+                    options.AddEventHandler<OpenIddictValidationEvents.ProcessAuthenticationContext>(configuration =>
+                    {
+                        configuration
+                            .UseSingletonHandler<HideBackOfficeTokensHandler>()
+                            // IMPORTANT: the handler must be AFTER the built-in query string handler, because the client-side SignalR library sometimes appends access tokens to the query string.
+                            .SetOrder(OpenIddict.Validation.AspNetCore.OpenIddictValidationAspNetCoreHandlers.ExtractAccessTokenFromQueryString.Descriptor.Order + 1);
+                    });
+                }
             });
 
         builder.Services.AddRecurringBackgroundJob<OpenIddictCleanupJob>();
         builder.Services.ConfigureOptions<ConfigureOpenIddict>();
+
+        if (hideBackOfficeTokens)
+        {
+            builder.AddNotificationHandler<UserLogoutSuccessNotification, HideBackOfficeTokensHandler>();
+        }
     }
 }

src/Umbraco.Core/Configuration/Models/BackOfficeTokenCookieSettings.cs

@@ -0,0 +1,31 @@
+using System.ComponentModel;
+
+namespace Umbraco.Cms.Core.Configuration.Models;
+
+/// <summary>
+///     Typed configuration options for back-office token cookie settings.
+/// </summary>
+[UmbracoOptions(Constants.Configuration.ConfigBackOfficeTokenCookie)]
+[Obsolete("This will be replaced with a different authentication scheme. Scheduled for removal in Umbraco 18.")]
+public class BackOfficeTokenCookieSettings
+{
+    private const bool StaticEnabled = false;
+
+    private const string StaticSameSite = "Strict";
+
+    /// <summary>
+    ///     Gets or sets a value indicating whether to enable access and refresh tokens in cookies.
+    /// </summary>
+    [DefaultValue(StaticEnabled)]
+    [Obsolete("This is only configurable in Umbraco 16. Scheduled for removal in Umbraco 17.")]
+    public bool Enabled { get; set; } = StaticEnabled;
+
+    /// <summary>
+    ///     Gets or sets a value indicating whether the cookie SameSite configuration.
+    /// </summary>
+    /// <remarks>
+    ///     Valid values are "Unspecified", "None", "Lax" and "Strict" (default).
+    /// </remarks>
+    [DefaultValue(StaticSameSite)]
+    public string SameSite { get; set; } = StaticSameSite;
+}

src/Umbraco.Core/Constants-Configuration.cs

@@ -64,6 +64,7 @@ public static class Configuration
         public const string ConfigWebhook = ConfigPrefix + "Webhook";
         public const string ConfigWebhookPayloadType = ConfigWebhook + ":PayloadType";
         public const string ConfigCache = ConfigPrefix + "Cache";
+        public const string ConfigBackOfficeTokenCookie = ConfigSecurity + ":BackOfficeTokenCookie";
 
         public static class NamedOptions
         {

src/Umbraco.Core/DependencyInjection/UmbracoBuilder.Configuration.cs

@@ -86,7 +86,8 @@ public static IUmbracoBuilder AddConfiguration(this IUmbracoBuilder builder)
             .AddUmbracoOptions<HelpPageSettings>()
             .AddUmbracoOptions<DataTypesSettings>()
             .AddUmbracoOptions<WebhookSettings>()
-            .AddUmbracoOptions<CacheSettings>();
+            .AddUmbracoOptions<CacheSettings>()
+            .AddUmbracoOptions<BackOfficeTokenCookieSettings>();
 
         // Configure connection string and ensure it's updated when the configuration changes
         builder.Services.AddSingleton<IConfigureOptions<ConnectionStrings>, ConfigureConnectionStrings>();