Authentication API
 | APIs used for and during authentication |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since 11.6RC1 |
Table of contents
Description
This module provides API used for and during the authentication.
In particular this module provides APIs:
- to triggers additional security checks when a user failed to authenticate multiple times in a given time window
- to allows users reset their password when they forgot it
- to manage the dedicated /authenticate/ URL resource type.
Configuration
The configuration of the module allows to setup three information:
- the authentication failure strategies (default is CAPTCHA)
- the maximum number of failing login attempts authorized before activating a strategy (default is 3)
- the time window during which those attempts should occur (default is 5 minutes)
Setting no strategy or 0 to the maximum number of attempts, or to the time window will disable the feature.
This configuration is available in the Administration > Authentication page by default.
Starting with it is now possible to enable or disable the authentication security mechanism. Note that disabling it will also clear out all information related to the login failures: this might unlock some users in case of problems.
Authentication Security Checks
Authentication Failure Manager
This component is responsible to record the authentication failures, and to trigger the strategies based on the given configuration.
Authentication Failure Strategies
Two strategies are currently implemented and available.
CAPTCHA
This is the default strategy. When a user reached the limit number of authentication attempts, a CAPTCHA is displayed in the login page, and the user have to solve it in order to be login.
Disable Account
This strategy will automatically disable the user account in case of repeated authentication failure. In that case he needs to contact an administrator of the wiki to enable it back.
Authenticate URL resource type
This module provides the component to handle the /authenticate/ URLs.
This URL allows to handle two actions with the following schemes:
- /authenticate/resetpassword allows a user to reset her password
- /authenticate/retrieveusername allows a user to retrieve her username
Reset password
A dedicated component is provided to allow a user who forgot her password to retrieve it. The process is using an intermediate code that needs to be sent to the user by a protected mean such as an email sent to her.
It's possible to configure the behaviour of the reset password email link, through a configuration in xwiki.properties:
XWiki 16.3.0+
#-# [Since 14.0RC1]
#-# Define the lifetime of the token used for resetting passwords in minutes.
#-# Default value is 60 meaning that users have 1 hour to access the link sent by email for performing password reset.
#-# Once the password is reset using the link, the token is revoked.
#-# Using 0 here means that the token has no expiration date, however it will be revoked at first wrong access.
#-#
#-# The value is in minutes. The default is:
# security.authentication.resetPasswordTokenLifetime = 60
XWiki <16.3.0
The configuration used to be slightly different with a default value set to 0:
#-# [Since 14.0RC1]
#-# Define the lifetime of the token used for resetting passwords in minutes. Note that this value is only used after
#-# first access.
#-# Default value is 0 meaning that the token is immediately revoked when first accessed.
#-# Use a different value if the reset password email link might be accessed several times (e.g. in case of using an
#-# email link verification system): in such case the user will have the defined lifetime to use again the email link.
#-#
#-# The default is:
# security.authentication.resetPasswordTokenLifetime = 0
Events
List of provided events:
- AuthenticationFailureEvent which is triggered whenever a user fails his authentication
- AuthenticationFailureLimitReachedEvent which is triggered when the authentication failure manager detected that a user reached the limit of authentication failures.
- XWiki 13.3+ Form and Basic authenticators trigger the new event UserAuthenticatedEvent whenever a user authenticates.
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).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-security-authentication-api 16.10.1):
- org.xwiki.commons:xwiki-commons-observation-api 16.10.1
- org.xwiki.platform:xwiki-platform-security-api 16.10.1
- securityfilter:securityfilter 2.0
- org.xwiki.platform:xwiki-platform-resource-api 16.10.1
- org.xwiki.platform:xwiki-platform-user-api 16.10.1
- org.xwiki.platform:xwiki-platform-model-api 16.10.1
