Backend routing¶
Each request to the backend is eventually executed by a controller. A list of routes is defined which maps a given request to a controller and an action.
Routes are defined inside extensions, in the files
Configuration/Backend/Routes.php
for general requestsConfiguration/Backend/AjaxRoutes.php
for Ajax calls
Here is an extract of EXT:backend/Configuration/Backend/Routes.php:
So, a route file essentially returns an array containing route mappings. A route
is defined by a key, a path, a referrer and a target. The "public" access
property indicates that no authentication is required for that action.
Note
The current route object is available as route attribute in the PSR-7 request object of every
backend request. It is added through the PSR-15 middleware stack and can be
retrieved using $request->getAttribute('route')
.
Backend routing and cross-site scripting¶
Public backend routes (those having option 'access' => 'public'
) do not
require any session token, but can be used to redirect to a route that requires
a session token internally. For this context, the backend user logged in must
have a valid session.
This scenario can lead to situations where an existing cross-site scripting vulnerability (XSS) bypasses the mentioned session token, which can be considered cross-site request forgery (CSRF). The difference in terminology is that this scenario occurs on same-site requests and not cross-site - however, potential security implications are still the same.
Backend routes can enforce the existence of an HTTP referrer header by adding a
referrer
to routes to mitigate the described scenario.
'main' => [
'path' => '/main',
'referrer' => 'required,refresh-empty',
'target' => Controller\BackendController::class . '::mainAction'
],
Values for referrer
are declared as a comma-separated list:
required
enforces existence of HTTPReferer
header that has to match the currently used backend URL (for example,https://example.org/typo3/
), the request will be denied otherwise.refresh-empty
triggers an HTML-based refresh in case HTTPReferer
header is not given or empty - this attempt uses an HTML refresh, since regular HTTPLocation
redirect still would not set a referrer. It implies this technique should only be used on plain HTML responses and will not have any impact, for example, on JSON or XML response types.
This technique should be used on all public routes (without session token) that internally redirect to a restricted route (having a session token). The goal is to protect and keep information about the current session token internal.
The request sequence in the TYPO3 Core looks like this:
HTTP request to
https://example.org/typo3/
having a valid user sessionInternally public backend route
/login
is processedInternally redirects to restricted backend route
/main
since an existing and valid backend user session was found + HTTP redirect tohttps://example.org/typo3/main?token=...
+ exposing the token is mitigated withreferrer
route option mentioned above
Attention
Please keep in mind these steps are part of a mitigation strategy, which requires to be aware of mentioned implications when implementing custom web applications.
Generating backend URLs¶
Using the UriBuilder API, you can generate any kind of URL for the backend, may
it be a module, a typical route or an Ajax call. Therefore use either
buildUriFromRoute()
or buildUriFromRoutePath()
. The
UriBuilder
then returns a PSR-7 conform Uri
object that can be
cast to a string when needed. Furthermore, the UriBuilder
automatically
generates and applies the mentioned session token.
Example within a controller (we use here a non-Extbase controller):
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Controller;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Routing\UriBuilder;
final class MyRouteController
{
private UriBuilder $uriBuilder;
public function __construct(UriBuilder $uriBuilder)
{
$this->uriBuilder = $uriBuilder;
}
public function handle(ServerRequestInterface $request): ResponseInterface
{
// .. do some stuff
// Using a route identifier
$uri = $this->uriBuilder->buildUriFromRoute(
'web_layout',
['id' => 42]
);
// Using a route path
$uri = $this->uriBuilder->buildUriFromRoutePath(
'/record/edit',
[
'edit' => [
'pages' => [
123 => 'edit',
],
],
]
);
// ... do some other stuff
}
}
More Information¶
Please refer to the following resources and look at how the TYPO3 source code handles backend routing in your TYPO3 version.