Skip to content

Documented ApplicationUrlDetection (17.4) #8024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sofietoft merged 1 commit into from
Apr 30, 2026
Merged

Documented ApplicationUrlDetection (17.4) #8024

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions 17/umbraco-cms/reference/configuration/webroutingsettings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ An example of a web routing config with default values, and a placeholder for th
"DisableRedirectUrlTracking": false,
"UrlProviderMode": "Auto",
"UmbracoApplicationUrl": "http://www.mysite.com/",
"ApplicationUrlDetection": "None",
"UseStrictDomainMatching": false
}
}
Expand Down Expand Up @@ -100,12 +101,28 @@ Will set the URL provider mode, options are:

## Umbraco application URL

Defines the Umbraco application URL that the server should reach itself. By default, Umbraco will guess that URL from the first request made to the server. Use this setting if the guess is not correct (because you are behind a load-balancer, for example). Format is: `http://www.mysite.com/`, ensure to contain the scheme (http/https) and complete hostname.
Defines the Umbraco application URL that the server should reach itself. This URL is used in features such as password reset links, user invitations, and other email notifications, as well as for some health checks. The format is: `http://www.mysite.com/` and must contain the scheme (http/https) and complete hostname.

When this setting is provided, it always takes precedence over any value detected through `ApplicationUrlDetection`. Setting an explicit value is the recommended approach for production environments.

{% hint style="info" %}
Previously before v9, it was required to specify **backoffice** path as this was customizable (`/umbraco` by default). However, from v9+ this is no longer possible, so it's sufficient to use the URL that contains the scheme (http/https) and complete hostname.
Previously before v9, it was required to specify the **backoffice** path as this was customizable (`/umbraco` by default). However, from v9+ this is no longer possible, so it's sufficient to use the URL that contains the scheme (http/https) and complete hostname.
Comment thread
sofietoft marked this conversation as resolved.
{% endhint %}

## Application URL detection

Controls how Umbraco determines the application URL when `UmbracoApplicationUrl` has not been set explicitly. Available options are:

* `None` (default): No auto-detection takes place. The application URL must be set explicitly via `UmbracoApplicationUrl`. Operations that require it (such as user invitations and password resets) will fail with a `400 Bad Request` response indicating that the application URL is not configured.
* `FirstRequest`: The application URL is set from the first HTTP request received by the server, after which it is locked. Subsequent requests with different `Host` headers are ignored.
* `EveryRequest`: The application URL is set from the first HTTP request and can be overwritten by every subsequent request.

{% hint style="warning" %}
Copy link
Copy Markdown

@github-actions github-actions Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

In environments where Umbraco is not behind a reverse proxy that validates the `Host` header, allowing auto-detection (`FirstRequest` or `EveryRequest`) can enable a forged `Host` header to influence the URL used in email notifications. Explicitly configuring `UmbracoApplicationUrl` is the recommended approach.
{% endhint %}

`UmbracoApplicationUrl` always takes precedence over the value derived through `ApplicationUrlDetection`.

## Strict domain matching

With multi-site setups multiple root nodes will be prepared with assigned domains. When routing a request, the content matched by path below the root node that matches the domain is returned.
Expand Down
21 changes: 19 additions & 2 deletions 18/umbraco-cms/reference/configuration/webroutingsettings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ An example of a web routing config with default values, and a placeholder for th
"DisableRedirectUrlTracking": false,
"UrlProviderMode": "Auto",
"UmbracoApplicationUrl": "http://www.mysite.com/",
"ApplicationUrlDetection": "None",
"UseStrictDomainMatching": false
}
}
Expand Down Expand Up @@ -100,12 +101,28 @@ Will set the URL provider mode, options are:

## Umbraco application URL

Defines the Umbraco application URL that the server should reach itself. By default, Umbraco will guess that URL from the first request made to the server. Use this setting if the guess is not correct (because you are behind a load-balancer, for example). Format is: `http://www.mysite.com/`, ensure to contain the scheme (http/https) and complete hostname.
Defines the Umbraco application URL that the server should reach itself. This URL is used in features such as password reset links, user invitations, and other email notifications, as well as for some health checks. The format is: `http://www.mysite.com/` and must contain the scheme (http/https) and complete hostname.

When this setting is provided, it always takes precedence over any value detected through `ApplicationUrlDetection`. Setting an explicit value is the recommended approach for production environments.

{% hint style="info" %}
Previously before v9, it was required to specify **backoffice** path as this was customizable (`/umbraco` by default). However, from v9+ this is no longer possible, so it's sufficient to use the URL that contains the scheme (http/https) and complete hostname.
Previously before v9, it was required to specify the **backoffice** path as this was customizable (`/umbraco` by default). However, from v9+ this is no longer possible, so it's sufficient to use the URL that contains the scheme (http/https) and complete hostname.
Copy link
Copy Markdown

@github-actions github-actions Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[UmbracoDocs.UmbracoTerms] Use 'Umbraco' instead of 'umbraco.' for consistency.

{% endhint %}

## Application URL detection

Controls how Umbraco determines the application URL when `UmbracoApplicationUrl` has not been set explicitly. Available options are:

* `None` (default): No auto-detection takes place. The application URL must be set explicitly via `UmbracoApplicationUrl`. Operations that require it (such as user invitations and password resets) will fail with a `400 Bad Request` response indicating that the application URL is not configured.
* `FirstRequest`: The application URL is set from the first HTTP request received by the server, after which it is locked. Subsequent requests with different `Host` headers are ignored.
* `EveryRequest`: The application URL is set from the first HTTP request and can be overwritten by every subsequent request.

{% hint style="warning" %}
Copy link
Copy Markdown

@github-actions github-actions Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

In environments where Umbraco is not behind a reverse proxy that validates the `Host` header, allowing auto-detection (`FirstRequest` or `EveryRequest`) can enable a forged `Host` header to influence the URL used in email notifications. Explicitly configuring `UmbracoApplicationUrl` is the recommended approach.
{% endhint %}

`UmbracoApplicationUrl` always takes precedence over the value derived through `ApplicationUrlDetection`.

## Strict domain matching

With multi-site setups multiple root nodes will be prepared with assigned domains. When routing a request, the content matched by path below the root node that matches the domain is returned.
Expand Down
Loading