This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.
This page allows you to configure exceptions to the WAF filtering rules. Why you need that? Some components are designed to properly and safely parse and use data which triggers WAF protection rules. Most usually, a component accepts an absolute path to files on your server or can parse complex data which normally trigger WAF's filters. Without any exceptions set, these components would be blocked and you wouldn't be able to properly use your site. The workaround was to disable WAF's filters, but this ended up in degrading the security of your site. Using the WAF Exceptions view you can fine tune which components, views and query parameters are in the "safe list" and should never be blocked.
WAF Exceptions is a very useful and powerful tool. It's also possible that you apply too many exceptions, opening potential security wholes in the firewall. Be very cautious when using it. Please keep in mind that when you add an exception, WAF is COMPLETELY TURNED OFF for all requests matching the exception. If you apply a too broad exception you will be deteriorating your site's security to the level it was before installing Admin Tools.
You create a new WAF Exception by clicking on the green New button at the toolbar which is located at the top of the page. The fields under the toolbar are filters: you can use them to filter the display of WAF Exception rules. They will NOT create a new WAF Exception. As a rule of thumb, which applies to all Joomla! components, if you don't see abutton at the top of the page you need to press the green New button before being able to create something.
WAF Exceptions are defined by specifying a combination of three things:
Component. Which component the
exception applies to. For example, if you want to disable
filtering for a query parameter in JCE you will have to set this
com_jce. If you want to apply the exception to
all components, no matter what, leave this blank.
View. Each component has one or several
views. When you turn off SEF you see something like
Note the view=example part in this URL; this tells Joomla! that
the view name (i.e. the area of the component we want to use) is
example. As you might have guessed, the View
option in a WAF Exception allows you to target the exception to
exactly one view. If you leave it blank, the exception will match
Components using the classic Joomla! MVC might use a
different notation, like
. Note the
task=item.edit part; its value (item.edit)
is a composition. The part to the left of the dot (item) is the
View you need to use in the WAF Exception. Support for this
Joomla! feature was added in Admin Tools 4.3.1; earlier versions
cannot define WAF exceptions for components using this
Due to the way Joomla! works, if you are using Joomla!'s SEF URLs it is possible that WAF Exceptions will not work with some components. In this case, change the ordering of the System - Admin Tools and your SEF router plugins so that the SEF router plugin is published BEFORE Admin Tools' plugin. This way Admin Tools will not be able to protect your site against potential vulnerabilities in your SEF component, but it will be able to apply WAF Exceptions even when SEF URLs are turned on.
Query Parameter. Everything after the
question mark in a non-SEF URL is called the URL query. You will
see a lot of key/value pairs, like
category=1:test and so on. The word at the left hand
side of the equals sign is called the Query
Parameter. The same-named parameter in WAF Exceptions
allows you to target a very specific query parameter. If you leave
it blank, all query parameters will be matched.
You can not leave all three options blank. That would match all components, all views and all query strings or, in other words, EVERY PAGE you access. This would imply that WAF would be effectively turned off. Admin Tools detects an attempt to do that and won't allow you to perform such a change.
The best way to understand WAF exceptions is by some practical examples.
Whole-component exception. Set
com_jce, leave view and query parameter
empty. This tells WAF that if it sees a request for JCE's utility
component (com_jce) is should turn off WAF no matter which view or
which query parameters are set. Essentially, WAF is turned off for the
entire JCE component.
Excepting a single component's
view. Let's say we want to disable WAF for all front-end
logins to avoid a complex password throwing a 403 error to our users.
Front-end logins are handled by com_user's login view. So just set
com_user, view to
and leave the query parameter blank. WAF is now disabled for the
login/logout page of your site.
Excepting a query parameter of a specific
component and view. Let's say we have a com_foobar
component whose test view accepts a pass parameter. Strong passwords
may accidentally trigger WAF. Just create a new exception where
com_foobar, view is
test and query parameter is
WAF will not deal with that specific query parameter on that specific
component and view, but will be triggered by unsafe content passed in
any other query parameter on that particular view.
Excepting a query parameter across all
components and views. Let's say that you see a lot of 403s
in your site because various components use a password query parameter
to accept passwords and, as we mentioned above, complex passwords can
trigger WAF. Instead of hunting down all the views across all
components, you can simply leave component and view empty and set the
query parameter to
password. From now on, when WAF
sees a password parameter coming into Joomla! it will not try to apply
its protection filters against it. If other query parameters come in
with the user request they will be filtered and, if they contain
unsafe content, the request will still be blocked.