Blocking Authenticator - UI

Last modified by Admin on 2022/02/07 00:20

cogUI for the blocking authenticator to configure blocking criteria and manage blocked users
Developed by

Clemens Robbenhaar

Active Installs2
0 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


This extension implements something similar to the "Authentication Security Module" introduced in XWiki 11.6. If you use XWiki 11.6 or newer, you are unlikely to need this extension; it is meant to be helpful if you are running older versions of XWiki and still want some protection against brute force password cracking.

This extension adds an authenticator to your wiki that temporarily blocks users and IPs after a configured number of login failures are recorded for that login or IP. It also adds a section to the XWiki Administration where you can configure the number of failed logins to trigger the blockage and the duration of the blockage, and where you can view and selectively unblock users and IPs.

Because this information is only stored in memory and not on persistent storage, the blockings go away if you restart your XWiki instance.
On the other hand the configuration about the number of failures is stored persistently and does not get reset.

If you have a wiki that has been in use for a long time, so that it still has an account named "Admin" as predefined adminstrative user, please set up another user with administrative privileges and a less conspicuous login. Otherwise this extension might lock you out from your admin account every time someone tries to guess the "Admin" password.


After you installed this extension and configured the xwiki.authentication.authclass, you can find a new section "Blockings" in the "Users" category of the wiki administration. If you click on that section you should see a screen with a list of blocked users and/or IPs followed by a configuration section.


If instead you see an error message, then it is likely that XWiki is not configured to use the blocking authenticator. Please review your configuration in the xwiki.cfg config file.

Otherwise you can review and adjust the initial configuration: 

Configuration section. Note that the values displayed are already modified from the defaults.

First you can define how many failed login attempts are necessary before the login is blocked. A value of 0 disables this feature. The default value is 3.

The next field defines for how long a login remains blocked after enough failures have accumulated. This is also the time frame for how long failed logins are remembered from the past. (A successful login always resets the counter to 0.)

The default value is 900 seconds = 15 minutes. You might want to set this to a much higher value if you prefer.

Similarly there is a counter for blocking an IP for failed logins, no matter for which login. The default value is 0, e.g. no blocking by IP. Before you activate this by setting it to a nonzero value you might check the other configuration settings to prevent locking out yourself.

The "Time of blockage" again is the time (given in seconds) that a blocked IP remains blocked.

The "List of whitelisted IPs" can contain a comma or space separated list of IPs which are excluded from being blocked. If your organization is running XWiki on an external server ("in the cloud"), then you might add the gateway IP(s) of your organization here if these are static IPs. This should prevent to lock out everyone using the same gateway just because several of your users manage to mistype their password at the same time (the "Monday morning fail").
The default value is empty, which means no whitelisted IPs.

In case you have a reverse proxy running in front of XWiki, the next setting allows this proxy to pass on the actual IP of the visitor. Otherwise the authenticator will see the IP or the reverse proxy instead.
Below the configuration form you can see the IP of your own request. If this is the same IP as your reverse proxy, you might add it to the list of trusted proxies, save the form and check if your displayed IP is updated to the actual IP with which you access the internet.
The default values are the IPv4 and IPv6 values for "localhost", which should be ok if the reverse proxy is on the same server as the XWiki. If you have no reverse proxy set up then you can safely remove these entries.

Please note: if you use a proxy to access the internet (not a reverse proxy in front of the XWiki server), then you do not have to add it to the list of trusted proxies. More likely you want to add that IP to the whitelist.

As the login failures are not stored in any persistent storage, restarting the server/servlet container for XWiki erases all blocking information. This can be used as a last resort if this authentication has locked you out completely out of your wiki.

Review and Unblock Users and IPs

Above the configuration section you can see information about the currently blocked logins and IPs.

An example with two blocked logins, one belonging to an actual XWiki user, and one blocked IP.

For both, blocked logins and blocked IPs, either you see a notice that nothing is blocked or a list of blocked values. In case of logins the entries are linked to the actual user profile if there is one (i.e. it is the login of an existing XWiki user.)

Behind each entry there is a link to unblock that entry immediately. No confirmation dialog will come up; instead the unblocking action is performed without further interaction.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Post-install File System Level Configuration

After you have installed the extension, the authenticator needs to be enabled. 

If you have subwikis, you must choose Install on Farm when installing the extension as otherwise logins will fail for wikis where the extension is not installed.

This has to be done on the file system in the configuration file xwiki.cfg; please set:


Afterwards you need to restart the XWiki server to makes these changes effective.

Error message after update

If you get an error message after updating the extension, like:

The Blocking Authenticator is not the configured authentication service. Please set xwiki.authentication.authclass=org.xwiki.contrib.authentication.blocking.internal.BlockingAuthServiceImpl in your xwiki.cfg.

this means the old version is still running and the UI does not figure out that this is another verison of the same authenticator.

You need to restart the XWiki to get rid of this message. Unless you restart, the old version still blocks login attempt an keeps your wiki secure, but you cannot view the blocked users and IPs or unblock them via the UI. 

Release Notes




This release fixes several issues when using the authenticator with subwikis:


Dependencies for this extension (org.xwiki.contrib.authentication:authenticator-blocking-ui 1.3):


Get Connected