were introduced in the Java Servlet specification version 2.3. A filter
intercepts requests and responses to transform or use the information.
Filters typically do not themselves create responses but instead provide
universal functions that can be
attached to any type of servlet
Since the filter chain is responsible for request handling in Magnolia, the default chain illustrates how filters are used to process requests. This document provides minimal information on filters. For more, see Request processing and filters and the filters[filters] package.
Don’t change the filter order
Magnolia handles incoming requests to display a page through its own filter chain. Filters in the chain are executed in the order in which they are declared until a filter decides that it can fulfill the request.
When editing properties in the filter chain be careful. Always test the changes on test environment before applying it to production.
The job of the
ContentTypeFilter is to initialize the
It’s created and populated with:
AggregationState is accessible using
Content-Type header is not set by
ContentTypeFilter anymore. The
MIME type was incorrectly set according to the request extension. It is
now the responsibility of renderers/servlets to set the correct content
type. For instance
the content type.
is a GeoIP
filter that detects the user’s country using the IP address of the
request for personalization. It adds the
country to the aggregation state as a trait. If a GET parameter
Country#REQUEST_PARAMETER with an IP address is supplied, this address
is used to resolve the country, which is stored in the
is a visitor
filter that detects the type of visitor based on the current user and
cookies for personalization.
visitorCookies can be configured for returning and registered users.
(Applicable to the cookie name nodes, i.e. to
registered'' and ``new in the above examples.)
optional, default is
A security setting that prevents cookies from being read by potentially malicious code.
optional, default is
Setting the property to
CosMultipartRequestFilter checks to see if there are any binary uploads such as form attachments in the request, extracts the binaries and persists them in the JCR.
UnicodeNormalizationFilter normalizes the current URI to the NFC form that is used internally.
RegistrationFilter checks the validity of the registration of a DX Core installation and delegates to the registration form so that the user can enter the license key. The license is also checked in other parts of the code such as in the STK.
Handles incoming login requests and delegates to login handlers. The handlers are configured under this filter. LoginFilter verifies that user credentials have been authenticated so that only authenticated users can be made active users. Magnolia uses JAAS for authentication. For more information, see Security.
Redirecting via the
To increase the performance of the site
text type responses with the gzipped response. The trick in this filter
is that it passes a ResponseWrapper instead of the response object it
got in the
doFilter(..) call to the filter chain. After all the
following filters have been executed, content is extracted from the
ResponseWrapper, gzipped and written to the original response.
SiteMergeFilter merges channel variations with the site definition. Configurations under this filter override configuration done in the site definition. The filter sets the site definition in the aggregation state. In the Community Edition, this filter sets the site in the aggregation state. In DX Core, the multisite filter can also set the site.
LogoutFilter checks to see if
the logout attribute
mgnlLogout is set as a request parameter. If this
flag is found, the user will be logged out and the filter chain will
restart with the first filter.
401 and 403 HTTP response codes and
AccessDeniedExceptions. The filter
renders an appropriate
login form that can consist of a redirect or
HttpClientCallbacks with different configuration and behavior
can be configured for this filter.
Here is the client callback configuration for the Travel Demo members area redirect and login form.
|Both callback classes implement the HttpClientCallback interface and support their own configuration properties. A custom callback should implement this interface.|
RedirectClientCallback redirects to a configured path or URL. This is useful, for example in single sign-on (SSO) context where the login screen is handled by a different application, or to hide the login form from a public instance using a fronting server configuration.
FormClientCallback renders a login form using Freemarker and the template configured with
AbstractHttpClientCallback provides a number of filtering capabilities:
url. Current request URL decoded and without the context path.
originalUrl. Original request URL decoded and without the context path, but not modified by any filter.
The Multisite filter removes the first-level node name from the URL.
The methods provided by
CsrfSecurityFilter checks the HTTP referer header to ensure that the request is not a cross-site request forgery attack. When a possible CSRF attack is detected the system serves a 400 Bad Request status to the browser. Magnolia also logs a security warning to the audit log.
If you access Magnolia with a script, set the referer header in your script to ensure the script can access Magnolia. Similarly, if you embed Magnolia content into a different website, disable the CSRF filter or add a voter (see below) that bypasses the CSRF filter for any requests coming from the trusted URL.
The CSRF security filter causes a request to fail if:
The referer header is empty
Host: mysite.com/.magnolia/pages/adminCentral.html Referer:
The host part of the referer header does not match the requested host.
Host: mysite.com/.magnolia/pages/adminCentral.html Referer: hackersite.io
You can bypass the CSRF security filter with a voter.
By default, the filter is bypassed if:
The requested URL does not start with
/.magnolia. Only AdminCentral URLs are vulnerable to CSRF attacks. Other URLs are not checked.
The user is not authenticated for AdminCentral access. Only authenticated requests are vulnerable to CSRF attacks.
The request does not have query parameters.
The requested resource is somewhere in AdminCentral. Vaadin has its own CSRF protection so Magnolia hands the responsibility over to Vaadin.
You can create your own whitelist of referrer domains or URIs using a
voter. The filter is bypassed for the whitelisted referrers. In this
example, we bypass the filter for any requests referred by
Voter node. Name the node for example
Fully-qualified voter class name.
Header you are checking such as
Domain or URI pattern compliant to SimpleUrlPattern. The pattern must be present in the header for the filter to be bypassed.
Some builds of Internet Explorer don’t send the HTTP request header
referrer when submitting a
form or when opening a popup. If the referrer is not in the HTTP request
CsrfSecurityFilter#handlePossibleCsrf interprets the request
as potential CSRF attack which forces the user to log in on the popup.
(See MAGNOLIA-6211). To overcome this issue, add voter
class UserAgentVoter to
bypass CsrfSecurityFilter for Internet Explorer.
Below the node
allowed you can add a list of regular expressions to
match the HTTP header userAgent. In the example above we have bypassed
Internet Explorer 6 and 11.
To ensure the filter is bypassed, make sure to have at least one
property on the node
allowed with a value which will match the
userAgent of the browser for which you want to bypass the filter. (For
Internet Explorer 11, the userAgent
be Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko.)
|Always test changes on test environment before applying it to a production system. When adding an erroneous regular expression - you won’t access admin central anymore. (In such case you have to use Groovy Rescue App).|
grants or denies permission to a site when the site is requested through
a particular domain name. For example, if you only grant access to the
travel site through
www.travel.com, no other
URL can be used to access the content. When a user tries to access one
site’s content through another site’s domain name, the system displays a
HTTP 404 error (page not found). See
URISecurityFilter checks to
see if the active user has permission to access the requested URI. In DX
(included in the
UriSecurityFilter to provide site aware functionality.
The following constraints are considered in finding the permissions of the user:
URI ACLs of the user’s roles
URI ACLs of the user’s groups’ roles
Permissions on IP addresses
If the user does not have the permission to access the URI then JAAS will provide a login form. This default behavior of the URI security filter can be changed in JAAS configuration.
You can configure your own login form in the URI security filter to
replace the default Magnolia login form. The form is configured in
/server/filters/securityCallback/clientCallbacks. Here is an example
of a custom form used to grant public users access to a restricted
members area. Authentication is delegated to the custom form when a
particular URI is accessed.
If you do not grant permission to the custom login form path, a standard Magnolia login form is displayed, usually on the author instance.
RangeSupportFilter adds support for ranged requests. Ranged requests is used by iPhone and some other clients to stream videos. In contrast to Android phones, iPhone does not support any other method of streaming videos.
CacheFilter manages the Magnolia cache.
The cache filter checks if a requested resource is already stored in the
cache to avoid recreation of the resource. If the resource is in the
cache, then it will be written to the response and the filter chain
stops. If the resource is not found in the cache, then a
ResponseWrapper, which not only writes to the
but also saves the response, is passed to the chain. After the filters
that follow have been executed (and the requested resource created), the
content is extracted from the response wrapper and stored in the cache.
The cache filter is part of Cache core and the respective configuration can be found in the module configuration.
Finally, we arrive at the filter chain which does the page rendering and delivery. The filters are grouped in this filter chain so they share a co-bypass definition.
access to different
workspaces. By default,
Magnolia is connected with the
website workspace. Therefore a request
URI is interpreted as the path to a node in the
website workspace. If
you want to address nodes in other workspaces you need to specify a
repository mapping in
Whereas the URI security filter checks permissions on the URI, ContentSecurityFilter checks if the current user has permission to access the requested content resource. The following constraints are considered in finding the permissions of the user:
Workspace-specific ACLs of the user’s roles
Workspace-specific ACLs of the user’s groups’ roles
If the user does not have permission to the resource, then JAAS will provide a login form. This default behavior of the content security filter can be changed in JAAS configuration.
Content node of the requested page
NodeDataobject of the requested data
Template if a template is connected with the
is a personalization filter that wraps
nodes. The filter tries to resolve a variant from the current node
AggregationState) using all available traits stored in the
TraitCollector and wraps it accordingly, if required. It only uses
PersonalizationNodeWrapper if a variant was resolved. Non-variants are
optional, default is
If set to
executes the component model before template rendering. The filter looks
for a request parameter containing the UUID of the component to execute.
The model can send output in which case page rendering is skipped, or
return a URI prefixed by
Finally, RenderingFilter is responsible for delivering the requested resource. If the requested resource is data, such as a file, then the data is just copied to the response.
The rendering filter is terminal, meaning it ends the filter chain and
filtering process. If no filter before it has been able to fulfill the
request and the rendering filter cannot find the page either, then a 404
Page not found error is returned. This is the default behavior.
You can change the behavior by adding a
terminateChain property under
the rendering filter and setting it to
false. When a request for a
page such as
/home/some/page is received and no such page exists in
the JCR, your own servlets can have a go at fulfilling the request. The
default value for the
terminateChain property is true.
Access to resources is defined in the
/modules/resources/config/resourceFilter filter. By default, the
filter allows access to resources as follows:
css, map, js, htm(l), ico, woff(2), ttf, svg, gif, jp(e)g, tiff, bmp
when located in the ``webresources’ directory
implementation class allows configuration of a filter for adding HTTP
headers to enable, for example,
resource sharing (CORS). The parameters configured in this filter are
added to the HTTP header if the filter is triggered. You can restrict
the filter’s scope by adding and configuring a
bypasses node to it.
For details please refer to the
main filter page.
Example configuration for CORS
Since Magnolia 6.2.4, you can use the
The example allows CORS with header types
Accept, with the
GET method, and from any origin:
The position of a filter within the filter chain matters. The appropriate position depends on the use case.
When using this filter to enable cross-origin resource sharing (CORS) -
place it after
Properties used in the example:
required, default is
Enables or disables the filter.
Class that implements the filter: AddHeadersFilter.
Headers allowed for the request.
The origin of the request (URL/host).
If you need a custom filter, please read Custom filters.