Filters

Java filters 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 or JSP page.

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 package.

Context

The first filter in the filter chain is the ContextFilter . This filter initializes MgnlContext which is local to the request and available on every further filter. The context provides a lot of useful functions, see  MgnlContext for details. Additionally the  AggregationState  is initialized and populated with:

• Character encoding
• Original URI
• Original URL
• Extension

The AggregationState is accessible using MgnlContext.getAggregationState().

Content type

The ContentTypeFilter  detects the correct MIME type and sets it in the response header.

Device detection

The  DeviceDetectionFilter  detects the type of device requesting content. Device detection is done using the Mobile Detect API.

Multipart request

The 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.

Unicode Normalization

The UnicodeNormalizationFilter normalizes the current URI to the NFC form that is used internally.

Registration

The RegistrationFilter checks the validity of the registration of an enterprise 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.

Login

Handles incoming login requests and delegates to login handlers. The handlers are configured under this filter. The LoginFilter checks to verify 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.

Activation

Handles incoming activation requests. This filter is the receiving part of the activation process.

Here is example how to use the bypass feature to avoid specific filters. This configuration will only handle requests where the URI starts with /.magnolia/activation.

The activation filter is implemented using ReceiveFilter from the Simple Exchange module. In the Enterprise Edition, the XAReceiveFilter (included in the Transactional Activation module) extends the ReceiveFilter to provide transaction related communications with syndicators.

GZip

To increase the performance of the site the GZipFilter replaces 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.

Channel

MultiChannelFilter resolves the channel to use by considering variations of the set channel. Resulting site gets set in  ExtendedAggregationState .

Site merge

SiteMergeFilter merges channel variations with the site definition. The configuration under this filter overrides 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 the Enterprise Edition, the multisite filter can also set the site.

Multisite

The MultiSiteFilter is an Enterprise Edition filter. It detects which site definition should be used. The filter makes site related properties available in the AggregationState .

Logout

The 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.

Security callback

The SecurityCallbackFilter handles 401 and 403 HTTP response codes and AccessDeniedExceptions. The filter renders an appropriate "login form" that can consist of a redirect or anything else.

Multiple HttpClientCallbacks with different configuration and behavior can be configured for this filter.

Here are the client callback configurations for the demo-project 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.

 Classes:

• RedirectClientCallback redirects to a configured path or URL. This is useful, for example in SSO contexts where the login screen is handled by a different application, or to hide the login form from a public instance using a frontingserver configuration.
• FormClientCallback renders a login form using Freemarker and the template configured with loginForm.

The AbstractHttpClientCallback class provides a number of filtering capabilities:

• url. Current request URL decoded and without the context path.
• urlPattern
• originalUrl. Original request URL decoded and without the context path, but not modified by any filter.
• originalUrlPattern
• hostPattern
• voters

For example, in a multisite installation for the request http://demoauthor.magnolia-cms.com/demo-project/about.html:

• url is /about.html
• originalUrl is /demo-project/about.html.

The Multisite filter removes the first-level node name from the URL.

Prior to Magnolia 4.5, this functionality resided in BaseSecurityFilter, URISecurityFilter and ContentSecurityFilter. These filters now merely set an HTTP response code or throw an exception, which is handled here.

CSRF security

 Magnolia 4.5.21+

The CSRF filter 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 user is redirected to the Magnolia login page. The system displays a notification to say that the referer header is required and logs a security warning to the audit log.

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

Bypassing the filter

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.

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 http://www.trustedsite.com.

Voter properties:

• <voter node>: Voter parent node. You can name the node for example as whitelist.
  
  • class: Fully-qualified voter class name. See examples below.
  • headerName: Header you are checking such as referer.  This is not a misspelling.
  • pattern: Domain or URI pattern compliant to SimpleUrlPattern . The pattern must be present in the header for the filter to be bypassed. 

Use these voter classes:

• info.magnolia.voting.voters.RequestHeaderPatternSimpleVoter: Checks for a URL pattern compliant to SimpleUrlPattern  such as http://www.trustedsite.*
• info.magnolia.voting.voters.RequestHeaderPatternRegexVoter : Checks for a regular expression pattern.

Cross site security

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 demo-project site through www.demo-project.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 Cross-site security

URI security

The URISecurityFilter checks to see if the active user has permission to access the requested URI. In the Enterprise Edition, SiteUriSecurityFilter (included in the   Extended Templating Kit module ) extends 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.

Range

The 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.

i18n content support

The I18nContentSupportFilter  detects the requested locale and sets the locale in the aggregation state. The filter rewrites the internal current URI, whether virtual or not. It does not rewrite the URI displayed to the user, however. See Language.

Cache

The 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 "standard" response, but saves the response is passed to the chain. After the following filters have been executed (and hopefully the requested resource has been created), the content is extracted from the ResponseWrapper and stored in the cache.

The cache filter is part of the Cache module and the respective configuration can be found in the cache module configuration.

Virtual URI

The VirtualUriFilter checks to see if the requested URI matches to a URI pattern defined in the modules configuration and executes the URI mapping.

Servlets filter chain

The servlets configured in modules are installed in Magnolia's servlets filter chain using the ServletDispatchingFilter as the implementing filter class. If the servlet mapping matches the URI, then the service(..) method of the servlet is called.

CMS filter chain

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.

Repository mapping

The RepositoryMappingFilter handles access to different repositories or 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 repository. If you want to address nodes in other workspaces you have to specify a repository mapping in /server/URI2RepositoryMapping.

Content security

Where the URI security filter above checked permissions on the URI. The 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 the permission to access the resource then JAAS will provide a login form. This default behavior of the content security filter can be changed in JAAS configuration.

Aggregator

The AggregatorFilter  analyses the request and stores the results in the  AggregationState . After this filter, every value the aggregation state can have is known.

Intercept

The InterceptFilter handles administrative requests from AdminCentral like

• Sort nodes
• Delete a node
• Switch to preview

Model execution

The ModelExecutionFilter 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 redirect, permanent or forward.

Softlocking

Provides collaboration information for the main bar in the page editor. The SoftLockingFilter checks whether the request is an AJAX request to interact with server-side soft locking support and which returns JSON results. Soft locking is an Enterprise Edition feature.

Rendering

Finally, the RenderingFilter is responsible for delivering the requested resource. If the requested resource is data (e.g. a file) then the data is just copied to the response.