Updated basic authentication details for use without backoffice (CMS 17.4)

17/umbraco-cms/SUMMARY.md

@@ -437,6 +437,7 @@
     * [Working with caching](reference/cache/examples/tags.md)
 * [Response Caching](reference/response-caching.md)
 * [Security](reference/security/README.md)
+  * [Basic Authentication](reference/security/basic-authentication.md)
   * [API rate limiting](reference/security/api-rate-limiting.md)
   * [BackOfficeUserManager and Events](reference/security/backofficeusermanager-and-notifications.md)
   * [Cookies](reference/security/cookies.md)

17/umbraco-cms/reference/configuration/basicauthsettings.md

@@ -1,11 +1,16 @@
 ---
-description: "Information on the basic authentication section"
+description: >-
+  Configuration reference for the Umbraco basic authentication settings
+  section in appsettings.json.
 ---
 
 # Basic Authentication Settings
 
-Allows you to configure the basic authentication settings for Umbraco. A basic authentication section fully populated with default values can be seen here:
+This article is a reference for the `Umbraco:CMS:BasicAuth` configuration section. For an overview of the feature, including the login flow, frontend-only deployments, and view customization, see the [Basic Authentication](../security/basic-authentication.md) article.
 
+A basic authentication section with all default values:
+
+{% code title="appsettings.json" %}
 ```json
 "Umbraco": {
   "CMS": {
@@ -16,31 +21,49 @@ Allows you to configure the basic authentication settings for Umbraco. A basic a
       "SharedSecret": {
         "HeaderName": "X-Authentication-Shared-Secret",
         "Value": null
-      }
+      },
+      "LoginViewPath": "/umbraco/BasicAuthLogin/Login.cshtml",
+      "TwoFactorViewPath": "/umbraco/BasicAuthLogin/TwoFactor.cshtml"
     }
   }
 }
 ```
+{% endcode %}
+
 ## AllowedIPs
 
-This is a comma-separated list of IP addresses you want to limit where the requests can come from.
+A comma-separated list of IP addresses to limit where requests can come from.
 
 ## Enabled
 
-If the value is set to `true`, the basic authentication is enabled. By default, the value is set to false.
+Enables or disables basic authentication. The default value is `false`.
 
 ## RedirectToLoginPage
 
-If the value is set to `true`, instead of showing the basic authentication popup in the browser, the user is redirected to the login page. This is required for external logins to work. By default, the value is set to false.
+When set to `true`, users are redirected to a standalone server-rendered login page at `/umbraco/basic-auth/login` instead of seeing the browser's native authentication popup. The default value is `false`.
+
+This setting is required for [External login providers](../security/external-login-providers.md) and [Two-factor Authentication](../security/two-factor-authentication.md) to work with basic authentication.
+
+{% hint style="info" %}
+When two-factor authentication is required for a user, the login flow redirects to the 2FA page automatically. This happens even when `RedirectToLoginPage` is set to `false`, because the browser's native popup cannot complete a 2FA flow.
+{% endhint %}
 
 ## SharedSecret
 
-A shared secret can be sent using an HTTP header to bypass the basic authentication. This can be valuable for server-to-server communication.
+A shared secret sent via an HTTP header to bypass basic authentication. This is useful for server-to-server communication.
 
 ### HeaderName
 
-The header name used to compare the shared secret. By default, the value is set to `X-Authentication-Shared-Secret`.
+The header name used to compare the shared secret. The default value is `X-Authentication-Shared-Secret`.
 
 ### Value
 
-The value of the shared secret. Must be a string longer than 0 characters to be enabled. The default value is `null`.
+The value of the shared secret. Must be a non-empty string to be enabled. The default value is `null`.
+
+## LoginViewPath
+
+Path to a custom Razor view for the login page. When omitted, the built-in login view is used. See [Customizing the login views](../security/basic-authentication.md#customizing-the-login-views) for details.
+
+## TwoFactorViewPath
+
+Path to a custom Razor view for the two-factor authentication (2FA) page. When omitted, the built-in 2FA view is used. See [Customizing the login views](../security/basic-authentication.md#customizing-the-login-views) for details.

17/umbraco-cms/reference/security/basic-authentication.md

@@ -0,0 +1,110 @@
+---
+description: >-
+  Protect the front-end of your Umbraco website with basic authentication
+  using backoffice user credentials.
+---
+
+# Basic Authentication
+
+Basic authentication protects the front-end of your Umbraco website using backoffice user credentials. When enabled, visitors must authenticate before accessing any page.
+
+The feature supports username and password login, two-factor authentication, and external login providers (Google, Microsoft, and others). Authentication uses a standalone server-rendered login page that works independently of the backoffice.
+
+## Enabling basic authentication
+
+Enable basic authentication in `appsettings.json`:
+
+{% code title="appsettings.json" %}
+```json
+"Umbraco": {
+  "CMS": {
+    "BasicAuth": {
+      "Enabled": true,
+      "RedirectToLoginPage": true
+    }
+  }
+}
+```
+{% endcode %}
+
+With `RedirectToLoginPage` set to `true`, visitors are redirected to a login page at `/umbraco/basic-auth/login`. With it set to `false`, the browser shows its native authentication pop-up.
+
+Set `RedirectToLoginPage` to `true` when using external login providers or two-factor authentication. The browser's native pop-up cannot complete these flows.
+
+For the full list of configuration options, see the [Basic Authentication Settings](../configuration/basicauthsettings.md) article.
+
+## Login flow
+
+When `RedirectToLoginPage` is set to `true`, the login flow works as follows:
+
+1. A visitor requests a protected page.
+2. The middleware redirects to `/umbraco/basic-auth/login?returnPath=...`.
+3. The visitor enters their backoffice credentials.
+4. If two-factor authentication is required, the visitor is redirected to `/umbraco/basic-auth/2fa`.
+5. On successful authentication, the visitor is redirected back to the original page.
+
+External login providers appear as buttons on the login page when configured. See the [External login providers](external-login-providers.md) article for setup instructions.
+
+{% hint style="info" %}
+When two-factor authentication is required for a user, the login flow redirects to the 2FA page automatically. This happens even when `RedirectToLoginPage` is set to `false`, because the browser's native pop-up cannot complete a 2FA flow.
+{% endhint %}
+
+## Frontend-only deployments
+
+Basic authentication works in frontend-only deployments where the backoffice is not available. To enable this, register `AddBackOfficeSignIn()` in your `Program.cs`:
+
+{% code title="Program.cs" %}
+```csharp
+builder.CreateUmbracoBuilder()
+    .AddCore()
+    .AddBackOfficeSignIn()
+    .AddWebsite()
+    .AddComposers()
+    .Build();
+```
+{% endcode %}
+
+`AddBackOfficeSignIn()` registers backoffice identity and cookie authentication without the full backoffice. This enables the standalone login page with support for two-factor authentication and external login providers.
+
+For details on the available configurations, see the [Service Registration](../service-registration.md) article.
+
+{% hint style="info" %}
+When using the full backoffice setup with `AddBackOffice()`, backoffice sign-in is included automatically. You do not need to add `AddBackOfficeSignIn()` separately.
+{% endhint %}
+
+## Customizing the login views
+
+The built-in login and 2FA pages use minimal styling and work without customization. To match your site's design, you can provide custom Razor views.
+
+Set the view paths in `appsettings.json`:
+
+{% code title="appsettings.json" %}
+```json
+"Umbraco": {
+  "CMS": {
+    "BasicAuth": {
+      "Enabled": true,
+      "RedirectToLoginPage": true,
+      "LoginViewPath": "~/Views/BasicAuth/Login.cshtml",
+      "TwoFactorViewPath": "~/Views/BasicAuth/TwoFactor.cshtml"
+    }
+  }
+}
+```
+{% endcode %}
+
+The login view receives a `BasicAuthLoginModel` with the following properties:
+
+- `ReturnPath` — the URL to redirect to after login.
+- `ErrorMessage` — an error message to display (null when no error).
+- `ExternalLoginProviders` — a list of configured external login providers to render as buttons.
+
+The 2FA view receives a `BasicAuthTwoFactorModel` with the following properties:
+
+- `ReturnPath` — the URL to redirect to after verification.
+- `ErrorMessage` — an error message to display (null when no error).
+- `TwoFactorProviders` — a list of available 2FA providers.
+
+{% hint style="info" %}
+Use the built-in views at `/umbraco/BasicAuthLogin/Login.cshtml` and `/umbraco/BasicAuthLogin/TwoFactor.cshtml` as a reference when creating custom views.
+{% endhint %}

17/umbraco-cms/reference/security/external-login-providers.md

@@ -43,14 +43,23 @@ This avoids Umbraco treating this call back as a potential request for content,
 
 ## Enable RedirectToLoginPage
 
-When you are configuring an external login for **backoffice users**, you need to enable RedirectToLoginPage in the [BasicAuth section](../../reference/configuration/basicauthsettings.md#redirecttologinpage).
+When you are configuring an external login for **backoffice users** with basic authentication, you need to enable `RedirectToLoginPage` in the [Basic Authentication Settings](../../reference/configuration/basicauthsettings.md#redirecttologinpage).
 
+{% code title="appsettings.json" %}
 ```json
   "Umbraco": {
     "CMS": {
       "BasicAuth": {
+        "Enabled": true,
         "RedirectToLoginPage": true
 ```
+{% endcode %}
+
+This redirects users to a standalone server-rendered login page where external provider buttons are displayed. Without this setting, the browser shows a native authentication popup that does not support external login providers.
+
+{% hint style="info" %}
+External login providers also work in frontend-only deployments where the backoffice is not available. Register `AddBackOfficeSignIn()` in your `Program.cs` to enable this. See the [Basic Authentication](basic-authentication.md) article for details.
+{% endhint %}
 
 ## Try it out
 

17/umbraco-cms/reference/security/two-factor-authentication.md

@@ -258,6 +258,10 @@ The following guide will take you through implementing an option for backoffice
 
 This guide will not cover setting up the UI for user login and edits as this is handled elsewhere in the CMS.
 
+{% hint style="info" %}
+Two-factor authentication also works with basic authentication, including in frontend-only deployments where the backoffice is not available. When a user with 2FA enabled logs in via the basic authentication login page, they are redirected to a standalone 2FA page at `/umbraco/basic-auth/2fa`. For frontend-only setups, register `AddBackOfficeSignIn()` in your `Program.cs`. See the [Basic Authentication](basic-authentication.md) article for details.
+{% endhint %}
+
 ### Example implementation for Authenticator Apps for Users
 
 As an example, the guide will use the [GoogleAuthenticator NuGet Package](https://www.nuget.org/packages/GoogleAuthenticator/). This package works for both Google and Microsoft authenticator apps. It can be used to generate the QR code needed to activate the app for the website.

17/umbraco-cms/reference/service-registration.md

@@ -14,12 +14,13 @@ By default, Umbraco registers all services: the backoffice, website rendering, a
 
 The following configurations are supported:
 
-<table data-full-width="false"><thead><tr><th width="139.5625">Configuration</th><th width="115.69140625" data-type="checkbox">AddCore()</th><th width="155.87109375" data-type="checkbox">AddBackOffice()</th><th width="138.25390625" data-type="checkbox">AddWebsite()</th><th width="164.05859375" data-type="checkbox">AddDeliveryApi()</th></tr></thead><tbody><tr><td>Full (default)</td><td>false</td><td>true</td><td>true</td><td>true</td></tr><tr><td>Website + Delivery API</td><td>true</td><td>false</td><td>true</td><td>true</td></tr><tr><td>Website Only</td><td>true</td><td>false</td><td>true</td><td>false</td></tr><tr><td><p>Delivery API</p><p>Only</p></td><td>true</td><td>false</td><td>false</td><td>true</td></tr></tbody></table>
+<table data-full-width="false"><thead><tr><th width="139.5625">Configuration</th><th width="105" data-type="checkbox">AddCore()</th><th width="160" data-type="checkbox">AddBackOfficeSignIn()</th><th width="145" data-type="checkbox">AddBackOffice()</th><th width="125" data-type="checkbox">AddWebsite()</th><th width="145" data-type="checkbox">AddDeliveryApi()</th></tr></thead><tbody><tr><td>Full (default)</td><td>false</td><td>false</td><td>true</td><td>true</td><td>true</td></tr><tr><td>Website + Delivery API</td><td>true</td><td>false</td><td>false</td><td>true</td><td>true</td></tr><tr><td>Website + Basic Auth</td><td>true</td><td>true</td><td>false</td><td>true</td><td>false</td></tr><tr><td>Website Only</td><td>true</td><td>false</td><td>false</td><td>true</td><td>false</td></tr><tr><td><p>Delivery API</p><p>Only</p></td><td>true</td><td>false</td><td>false</td><td>false</td><td>true</td></tr></tbody></table>
 
-The key distinction is between `AddBackOffice()` and `AddCore()`:
+The key distinctions between the registration methods are:
 
-* **`AddBackOffice()`** registers everything needed for the Umbraco backoffice, including the Management API, backoffice identity, and all supporting services.
 * **`AddCore()`** registers only the foundational Umbraco services — configuration, core services, web components, caching, and background jobs — without any backoffice-specific services.
+* **`AddBackOfficeSignIn()`** registers backoffice identity and cookie authentication without the full backoffice. Use this when you need [Basic Authentication](configuration/basicauthsettings.md) with backoffice credentials on a frontend-only server. This enables the standalone login page with support for two-factor authentication and external login providers.
+* **`AddBackOffice()`** registers everything needed for the Umbraco backoffice, including the Management API, backoffice identity, and all supporting services. This calls both `AddCore()` and `AddBackOfficeSignIn()` internally.
 
 `AddBackOffice()` calls `AddCore()` internally, so there is no need to call both.
 
@@ -31,6 +32,7 @@ The key distinction is between `AddBackOffice()` and `AddCore()`:
 
 * **Full (default)**: Traditional Umbraco with all features enabled.
 * **Website + Delivery API**: Front-end servers serving both rendered pages and headless content.
+* **Website + Basic Auth**: Front-end servers with basic authentication using backoffice credentials, but no backoffice UI.
 * **Website Only**: Front-end servers serving only rendered pages.
 * **Delivery API Only**: Pure headless API servers.
 
@@ -107,6 +109,43 @@ await app.RunAsync();
 ```
 {% endcode %}
 
+## Website with basic authentication (no backoffice)
+
+The following configuration is used for front-end servers that need [Basic Authentication](configuration/basicauthsettings.md) with backoffice credentials but no backoffice UI. This enables a standalone server-rendered login page with support for two-factor authentication and external login providers.
+
+{% code title="Program.cs" %}
+```csharp
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+
+builder.CreateUmbracoBuilder()
+    .AddCore()
+    .AddBackOfficeSignIn()
+    .AddWebsite()
+    .AddComposers()
+    .Build();
+
+WebApplication app = builder.Build();
+
+await app.BootUmbracoAsync();
+
+app.UseUmbraco()
+    .WithMiddleware(u =>
+    {
+        u.UseWebsite();
+    })
+    .WithEndpoints(u =>
+    {
+        u.UseWebsiteEndpoints();
+    });
+
+await app.RunAsync();
+```
+{% endcode %}
+
+{% hint style="info" %}
+`AddBackOfficeSignIn()` can also be combined with `AddDeliveryApi()` for servers that serve both rendered pages and headless content with basic authentication.
+{% endhint %}
+
 ## Website only
 
 The following configuration is used for front-end servers that only serve rendered pages. Neither the backoffice nor the Content Delivery API is available.