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.

1. vWAF identifies an HTTP request on a path for which the Authentication Handler has been configured. (1)
2. The Authentication Handler becomes active and sets the AUTH_SESSION_ID in the vWAF session (or uses an existing one).
3. 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).
4. The Authentication Handler calls authenticate on the Authentication Server Backend with AUTH_SESSION_ID / full request_URL / token_list as parameters. (2)
5. 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.
6. Authenticate returns with a redirect URL (pointing to the Authentication Server Frontend with the REQUEST_ID as argument) and an empty token list. (3)
7. The Authentication Handler sets the (empty) token list in the vWAF session and redirects to the given URL. (4)(5)
8. The Authentication Server Frontend parses the REQUEST_ID from the URL.
9. The Authentication Server Frontend calls get_tokenlist on the Authentication Server Backend with the REQUEST_ID as argument. (6)
10. The Authentication Server Backend retrieves the stored token list for the provided REQUEST_ID.
11. The Authentication Backend returns the token list to the Authentication Server Frontend. (7)
12. 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)
13. The Authentication Server Frontend calls set_tokenlist on the Authentication Server Backend with the REQUEST_ID and the token list. (10)
14. The Authentication Server Backend stores the authenticated token list under the REQUEST_ID, generates a RESPONSE_ID and associates it with the REQUEST_ID.
15. 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)
16. The Authentication Handler sets AUTH_SESSION_ID in the vWAF session (or uses the existing one).
17. 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.
18. The Authentication Handler calls authenticate on the Authentication Server Backend with AUTH_SESSION_ID / full request url / token list as parameters. (14)
19. The Authentication Server Backend parses the provided request URL. there’s a RESPONSE_ID, so the stored AUTH_SESSION_ID / token list is fetched.
20. 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.
21. The Authentication Server Backend returns the redirect to URL and finally the token list. (15)
22. The Authentication Handler stores the token list in the vWAF session.
23. The Authentication Handler sets AUTH_SESSION_ID in the vWAF session (or uses the existing one).
24. 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).
25. 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.

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