Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
Guide That Contains This Content
[+] Expand All
[-] Collapse All

    Response Processors: Login Processor

    The login processor is designed to add additional protection to the login dialogs throughout the protected site. By default, it will not provide any additional protection, and must be configured to protect specific login forms. Once a login form has been configured, the processor will begin to monitor the login attempts and start checking for abusive patterns.

    This processor is capable of detecting a wide variety of abuse patterns on a login dialog, as well as stopping these abusive activities. One key protection mechanism is to require a captcha if a user attempts to login to an account which has experienced more than 3 failed login attempts since the last successful login attempt. This ensures that a malicious user cannot brute force a specific username, because after 3 failed attempts, the brute force tool will be stopped by a captcha. This does not represent a counter response, but instead is built in functionality that applies to all users on the system. So if user "A" submits 3 bad passwords, and then user "B" submits a password for the same username, user "B" will get a captcha, as well as user "A" for any additional login attempts they try. As soon as a user successfully logs into the account, it will take another 3 failed login attempts before the next captcha is required.

    In addition to protecting against a single username being attacked with a brute force script, the processor also detects "User sharing", "User pooling", "Username scans", "Multi-User brute force scans". See the incident descriptions for more information on what these incidents represent and what counter responses will be activated as a result. In order to configure the Login Processor to protect a login form, edit the "Protected Login Pages" configuration parameter. Add a new row and provide the following information. It will be useful to look at the HTML source code of the login form as it will have critical information you will need to configure protection:

    • Name: The name of the login page (this is just for your reference, it can be anything)
    • URL Pattern: The Regular Expression used to identify a username/password submission. This pattern should match the "action" attribute of the HTML <FORM> tag wrapping the login dialog.
    • Username Field Type: The type of inputs used to submit a username. Normally this will be "POST Parameter", however other options are provided for more specialized login mechanisms.
    • Username Field Name Pattern: A regular expression used to match the name of the input the username is submitted with. Normally this is "username", but could be other variations such as "usr", "user", and so on. You can simply enter the name of the input in this field if a regular expression is not required.
    • Username Field Value Pattern: A regular expression used to extract the username from the input value. Normally this should just be "^.*$", but if the username is wrapped in JSON for example, you might need to create a more complex expression. The username is considered the first matching parenthesis group in the pattern.
    • Username Field Encoding: The type of data encoding used on the username. Normally this will be "Ascii", however if any client side encoding is performed, other encoding options are available.
    • Password Field Type: The type of inputs used to submit a password. Normally this will be "POST Parameter", however other options are provided for more specialized login mechanisms.
    • Password Field Name Pattern: A regular expression used to match the name of the input the password is submitted with. Normally this is "password", but could be other variations such as "pwd", "pass", and so on. You can simply enter the name of the input in this field if a regular expression is not required.
    • Password Field Value Pattern: A regular expression used to extract the password from the input value. Normally this should just be "^.*$", but if the password is wrapped in JSON for example, you might need to create a more complex expression. The password is considered the first matching parenthesis group in the pattern.
    • Password Field Encoding: The type of data encoding used on the password. Normally this will be "Ascii", however if any client side encoding is performed, other encoding options are available.
    • Failure Pattern Target: In order to identify a failed login attempt, the processor will search for a specific pattern in the response. This attribute specifies where to search for that pattern. Normally this would be "Body" to search the HTML body of the response.
    • Failure Pattern: The regular expression to search for to check and see if the login attempt was unsuccessful. Assuming the Failure Pattern Target is "Body", this would be something like "you have provided an invalid username and password". However the exact text will need to be set to whatever the site actually returns. View the source of the response after a failed login and search for the error text, so that you get the most accurate version possible. Simply copying the text from the rendered page can exclude embedded HTML tags which will cause the pattern to never match.
    • Failure Pattern Condition: Specifies whether finding the failure pattern means the login was unsuccessful, or whether not finding the pattern means the login was unsuccessful.
    • Success Pattern Target: In order to identify a successful login attempt, the processor will search for a specific pattern in the response. This attribute specifies where to search for that pattern. Normally this would be "Body" to search the HTML body of the response.
    • Success Pattern: The regular expression to search for to check and see if the login attempt was successful. Assuming the Success Pattern Target is "Body", this would be something like "you have successfully logged in". However the exact text will need to be set to whatever the site actually returns. View the source of the response after a successful login and search for something that only gets displayed on a successful login, so that you get the most accurate version possible. Simply copying the text from the rendered page can exclude embedded HTML tags which will cause the pattern to never match.
    • Success Pattern Condition: Specifies whether finding the success pattern means the login was successful, or whether not finding the pattern means the login was successful.
    • Require Captcha After: Specifies how many failed login attempts on the same username before requiring all future login attempts on that username to solve a captcha. Entering "0" will allow infinite attempts.

    Keep in mind that some website implementations allow login information to be posted to many different URLs. If that is the case, make sure the URL pattern is defined generically enough to match any URL the user might submit a login request to. Only submissions that match the URL pattern will be protected.

    Once a login form has been configured, it can be tested by attempting to login to the same username 4 or more times. You should be presented with a captcha. Next, solve the captcha and log in with the correct password. Then logout and attempt to login to the same username again. If you do not get a captcha, then the login form is configured correctly.

    Table 1: Login Processor Configuration Parameters

    Parameter

    Type

    Default Value

    Description

    Basic

    Processor Enabled

    Boolean

    True

    Whether traffic should be passed through this processor. Note that just because this processor is enabled, does not mean that any login forms are being protected. Login forms will not be protected until they are configured in the "Protected Login Pages" parameter.

    Protected Login Pages

    Collection

    None

    The list of pages that should be protected from login and account abuse. These pages should reflect the URL's that accept username's and passwords and allow login, not necessarily the pages that contain login forms. For example, if every page on the site had a login form, but they all submitted to login.php, then only login.php needs to be configured in this processor.

    Advanced

    Bad Request Block Response

    HTTP Response

    400 Error

    The response to return if the user issues a request that either is too large, or uses multipart and multi-part is disabled.

    Blocked Replay Response

    HTTP Response

    400 Error

    The response to return if the user attempts to submit the validated request multiple times using the same captcha answer, and that behavior is not allowed.

    Cancel URL

    String

    (empty)

    The URL to redirect the user to if they cancel the CAPTCHA. An empty value will hide the cancel button. If you would like the cancel button to take the user back, you may also use a value of “javascript:history.go(-1);" Suggested Value: None

    Captcha Binary Directory

    String

    Random

    The name of the directory where captcha images and audio files will be served from. This should not conflict with any actual directories on the site.

    Captcha Characters

    String

    abcdefhkmnprwxyz ABCEFGHJKLMNPQRTWXYZ 234678

    The characters to use when generating a random captcha value. Avoid using characters that can be easily mixed up. This set of characters is case sensitive.

    Captcha Expiration

    Integer

    120

    The maximum number of seconds the user has to solve the captcha before the request is no longer possible.

    Captcha State Cookie

    String

    Random

    The name of the cookie to use to track the active captchas that have not yet been solved. The cookie is only served to the captcha binary directory.

    Captcha Template

    File

    Default Template

    The HTML template used to ask the user to complete a captcha. This template must contain specific key words in order to integrate properly. Please refer to the manual for more information.

    Captcha Validation Input Name

    String

    Random

    The name of the form input used to transmit the captcha validation key. This should be obscure so that users who have not been required to enter a captcha cannot supply bad values to this input to profile the system.

    Expired Captcha Response

    HTTP Response

    400 Error

    The response to return if the user submits a validated request after the captcha has expired. This can happen if the user refreshes the results of the captcha long after they have solved it.

    Maximum Active Captchas

    Integer

    7

    The maximum number of captchas any given user can be solving at any given time. This limit can be overcome, but the majority of users will not be able to. This is primarily for performance, as the more active captchas that are allowed, the larger the state cookie becomes.

    Maximum Request Size

    Integer

    524288 (512KB)

    The maximum number of bytes in a request before it is considered not acceptable for captcha validation, and will be blocked.

    Support Audio Version

    Boolean

    True

    Whether an audio version of the captcha is provided to the user. This can be a requirement for accessibility, as vision impaired users would otherwise be unable to solve the captcha.

    Watermark

    String

    %DOMAIN

    The text to watermark the captcha with. This can be used to prevent the captcha from being used in a phishing attack. For example, an abuser would not be able to simply display the captcha on a different site and ask a user to solve it. The watermark would tip the user off that the captcha was not intended for the site they are visiting. Use %DOMAIN to use the domain name as the watermark.

    Incident: Site Invalid Login

    Boolean

    True

    The user has submitted an invalid username or password. This is just an informational incident and is used to identify more complex attacks. It is highly recommended that this incident not be disabled, as it can cause other incidents to no longer register.

    Incident: Site Login Multiple IP

    Boolean

    True

    The user has submitted a valid username and password or an invalid username and password for an account that has recently been used by a different IP. This is just an informational incident and is used to identify more complex attacks. It is highly recommended that this incident not be disabled, as it can cause other incidents to no longer register.

    Incident: Site Login Multiple Usernames

    Boolean

    True

    The user has submitted a valid username and password for more than one account recently. This is just an informational incident and is used to identify more complex attacks. It is highly recommended that this incident not be disabled, as it can cause other incidents to no longer register.

    Published: 2015-02-04