Authentication Handler

Purpose

This handler only has an effect when the Session Handler is also active. In detection mode, the Authentication Handler is ignored.

You can protect individual paths via authentication. By setting up different authentication zones you’re free to choose whether the paths use the same or different authentication. This is especially helpful if your web application doesn’t have a secure built-in authentication mechanism.

You’re free to provide your own authentication frontend.

To achieve authentication, the authentication framework involves the following components:

Authentication Handler in vWAF

Authentication Server Backend (also provided with vWAF )

Authentication Server Frontend (LDAP implementation provided with vWAF; can be customized)

The components of the authentication framework are configured in the configuration file zeusafm.conf (attributes see System Configuration).

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

For details regarding HTTP Basic Auth, see Hide Basic Auth Handler.

Severity

Events triggered by this handler are given the severity: medium.

For details on severity levels, see Severity of Events Triggered by Handlers.

How the authentication framework works

The components of the authentication framework interact as follows:

Authentication Handler

The Authentication Handler monitors access to the paths to which it was assigned. At least one “authorized token” is needed, else the handler starts an authentication cycle (see later in this section). It generates a unique AUTH_SESSION_ID per vWAF session (this ID is used by the Authentication Server Backend to identify a user).

The Authentication Handler communicates only with the Authentication Server Backend via a simple private interface (XMLRPC). In fact the communication from the Authentication Handler to the Authentication Server Backend goes through an “object callback channel”. The Authentication handler understands only some very simple commands like “redirect to url …” and “set following tokens …”.

Authentication Server Backend

The Authentication Server Backend holds a simple storage of AUTH_SESSION_IDs and the corresponding authorized tokens. There are two interfaces: a private one (XMLRPC) for the Authentication Handler, and a second one for the Authentication Server Frontend.

Interface to the Authentication Handler authenticate(AUTH_SESSION_ID, request_url, token_list) Returns a full URL where the handler should redirect to, and optionally a list of tokens (which the handler then stores in the vWAF session).

Interface to the Authentication Server Frontend:

get_tokenlist(REQUEST_ID) Returns the token_list for the given REQUEST_ID. The REQUEST_ID was generated by the Authentication Server Backend and associated with the AUTH_SESSION_ID and the wanted token_list during the authenticate call from the Authentication Handler. The Authentication Server Frontend extracts the REQUEST_ID from the redirect URL that was generated by the Authentication Server Backend.

set_tokenlist(REQUEST_ID, token_list) Returns a full URL where the Authentication Server Frontend should redirect to (this URL is the stored request_url with a generated RESPONSE_ID as parameter, similar to the REQUEST_ID).

Authentication Server Frontend

The Authentication Server Frontend is the interface to the authentication mechanism (LDAP, RADIUS, PAM, or equivalent). It provides a web server, or must at least provide an HTTP server that can retrieve the redirected authentication requests and somehow authenticate the user. It interacts with the Authentication Server Backend through a very simple interface that lets it retrieve the token list for a given REQUEST_ID and provides the possibility to authenticate the given REQUEST_ID.

Authentication cycle

A full authentication cycle runs as follows:

The numbers given in braces relate to the numbers given in the diagrams earlier in this section.

vWAF identifies an HTTP request on a path for which the Authentication Handler has been configured. (1)

The Authentication Handler becomes active and sets the AUTH_SESSION_ID in the vWAF session (or uses an existing one).

The Authentication Handler compares the token list (if any) in the vWAF session with the required token (the one configured by the attribute auth_zone of the handler).

The Authentication Handler calls authenticate on the Authentication Server Backend with AUTH_SESSION_ID / full request_URL / token_list as parameters. (2)

The Authentication Server Backend parses the provided request URL. there’s no RESPONSE_ID, so a new REQUEST_ID is generated and the AUTH_SESSION_ID / request_URL / token_list is stored under the new REQUEST_ID.

Authenticate returns with a redirect URL (pointing to the Authentication Server Frontend with the REQUEST_ID as argument) and an empty token list. (3)

The Authentication Handler sets the (empty) token list in the vWAF session and redirects to the given URL. (4)(5)

The Authentication Server Frontend parses the REQUEST_ID from the URL.

The Authentication Server Frontend calls get_tokenlist on the Authentication Server Backend with the REQUEST_ID as argument. (6)

The Authentication Server Backend retrieves the stored token list for the provided REQUEST_ID.

The Authentication Backend returns the token list to the Authentication Server Frontend. (7)

The Authentication Frontend tries to authenticate the user for the given token list (via LDAP, RADIUS or equivalent). If the user isn’t authenticated, the cycle stops here, else the user is authenticated for the given tokens (or a subset). (8)(9)

The Authentication Server Frontend calls set_tokenlist on the Authentication Server Backend with the REQUEST_ID and the token list. (10)

The Authentication Server Backend stores the authenticated token list under the REQUEST_ID, generates a RESPONSE_ID and associates it with the REQUEST_ID.

The Authentication Server Backend generates a redirect URL, which consists of the stored full request ID (from the handler request) and the RESPONSE_ID as argument. (11)(12)(13)

The Authentication Handler sets AUTH_SESSION_ID in the vWAF session (or uses the existing one).

The Authentication Handler compares the token list in the vWAF session (if any) with the required token list (the one configured by the attribute auth_zone of the handler). Still there’s no match.

The Authentication Handler calls authenticate on the Authentication Server Backend with AUTH_SESSION_ID / full request url / token list as parameters. (14)

The Authentication Server Backend parses the provided request URL. there’s a RESPONSE_ID, so the stored AUTH_SESSION_ID / token list is fetched.

The Authentication Server Backend now compares the stored AUTH_SESSION_ID with the given one (to make sure that the user didn’t simply steal the response ID). If it doesn’t match, the Authentication Server Backend returns a redirect URL to an errorpage. Else the RESPONSE_ID is stripped from the full request URL and this becomes the redirect to URL.

The Authentication Server Backend returns the redirect to URL and finally the token list. (15)

The Authentication Handler stores the token list in the vWAF session.

The Authentication Handler sets AUTH_SESSION_ID in the vWAF session (or uses the existing one).

The Authentication Handler compares the token list in the vWAFsession (if any) with the required token list (the one configured by the attribute auth_zone of the handler).

Now there’s a match. The user is authenticated for at least one token. The HTTP request gets through to the application. (16)(17)(18)

Recommendations for use

If your web application has no secure built-in authentication mechanism, use the Authentication Handler and the provided Authentication Framework to protect access to individual paths via authentication as required.

Attribute	Meaning
auth zone	Authentication zone: Token that’s required to access the path that’s protected by this handler. Currently you can only specify one single token here, not a list of tokens.
auth method	Specifies whether vWAF is to use internal or external authentication. internal means that the authentication mechanism of vWAF is used external means that an external service is used for authentication (for configuration, see External Authentication Framework)
auth server	Specifies the URL of the authentication service. This URL must be specified if you use external auth method. If you use internal auth method, the default URL is the URL of the authentication daemon, as specified in system configuration by the attributes authenticationServerIP and authenticationServerPort (see System Configuration).
auth cache timeout	Specifies for how many seconds vWAF stores the credentials in cache. The default value is 3600 seconds (= 1 hour).
fail open	Activate this option if you want vWAF to allow requests in case the authentication back-end can’t be accessed.
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).

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