Hide Basic Auth Handler

Purpose

The Hide Basic Auth Handler only has an effect if the Session Handler is active. In detection mode, the Hide Basic Auth Handler is ignored.

Web applications are frequently implemented with password protection via HTTP Basic Auth (e.g. via .htaccess file on the Apache web server). HTTP Basic Auth is usually very simple to add in and to maintain, and the web application doesn’t need to know anything about the authentication. However, HTTP Basic Auth also has several serious disadvantages:

  • The login page can’t be configured. Only a browser dialogue window appears. This means that the login can’t be modified to fit with a corporate identity, and no disclaimer, other information or tools can be provided.
  • No logout is possible. To force a logout, the user needs to close his browser.

With the Hide Basic Auth Handler, vWAF provides the user with the option to use a form-based login / logout without having to configure the web application and the web server. The Hide Basic Auth Handler lets an HTTP Basic Auth based authentication of the web server look like a session and form-based authentication to the user. The Hide Basic Auth Handler therefore combines the advantages of both login methods.

For more information regarding adding and editing Handlers, see Editing Handlers.

For more detailed authentication requirements, see Authentication Handler.

Severity

Events triggered by this handler are given the severity: low. (For details on severity levels, see Severity of Events Triggered by Handlers).

Workflow in detail

If the Hide Basic Auth Handler is active, vWAF examines each response of the web server as to whether it consists of an HTTP error code 401 (Authentication Required). In this case, vWAF doesn’t forward this response on to the client, but saves the URL of the failed request specifically for that session, and generates an HTTP redirect to a freely configurable login page.

The login page must contain the following form fields:

  • username
  • password
  • a further, hidden form field (type=hidden) with freely configurable name with the value login

If the user logs in via this login page, vWAF uses the values from username and password to determine the HTTP Basic Auth Token and stores it in the session. In each further request in this HTTP session, vWAF transparently inserts an appropriate HTTP Authentication Header into the request. To the web server, vWAF therefore emulates a browser using HTTP Basic Auth.

If a hidden form field (type=hidden) occurs with the value logout, vWAF deletes the credentials from the session and the user is logged out.

Recommendations for use

Use the Hide Basic Auth Handler to design an attractive login page and to allow the users of your web application to log out.

Attributes

Attribute Meaning

magic action

Name of the hidden form field containing either the value login or logout .

Example: demoaction

loginpage

Login page to which vWAF is to redirect instead of the HTTP-Basic Auth based login.

Example: /demo/login.html

usertext

Optional:

Here you can specify some text that vWAF adds to the log file entries created by this handler. You can use this, for example, to document why you've added the handler to your configuration, and how the handler is intended to behave.

enable logging

Disable this option if you do not want vWAF to create a log file entry when the handler is executed. This can be useful to keep log files smaller in case the handler creates a large number of entries but you don't need these entries.

When in detection mode, disabling logging de facto makes the handler ineffective. Disabling logging also prevents the actions of the handler from being taken into account for the Top-10 lists in Attack Analysis, and from being listed in Reports. To decrease the size of the log files, also consider to enable reduced logging, which excludes all non-handler-related information from the log files (see Editing Applications).

Required structure of the login page

The login page for your web application must contain the following fields:

  • username: input field for the username
  • password: input field for the password
  • Hidden field with the name specified under magic-action. The value of this field must be login.

HTML example:

<input type="hidden" name="demoaction" value="login">

For details regarding entries added to the log file by this handler, see the relevant section in Entries in Application-Specific Log Files.