--- title: Authentication Handler slug: ps/help/en_us/vwaf/ag/authentication-handler docTags: createdAt: 2026-08-02T10:05:40.799Z --- ## Purpose :::hint{type="info"} This handler only has an effect when the [Session Handler](docId:3LOwZUZAA4bdpX0WBThgO) 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) :::hint{type="info"} The components of the authentication framework are configured in the configuration file zeusafm.conf (attributes see [System Configuration](docId:3VcG4M4PeYN4G5D4tCsuL)). ::: :::hint{type="info"} For more information regarding adding and editing Handlers, see [Editing Handlers](docId:7HHz1jewuWOJC-FTlmBZw). ::: For details regarding HTTP Basic Auth, see [Hide Basic Auth Handler](docId\:m0Rbe2pziDvgdIvFXJ96r). ## Severity Events triggered by this handler are given the severity: medium. For details on severity levels, see [Severity of Events Triggered by Handlers](docId\:ZAdDmUem6-P614MEP_3aQ). ## How the authentication framework works The components of the authentication framework interact as follows: ::Image[]{src="https://api.archbee.com/api/optimize/wxZG1KsS4xNkVZYoiu_o9/jPhUQ5YIgeK5KEzGJP2BF_guid-4e34476b-c2ac-408a-a477-41c4119ed487-outputlow277x277.jpg" position="flex-start" size="28" width="277" height="277" initialPath="guid-4e34476b-c2ac-408a-a477-41c4119ed487-output_low_277x277.jpg" githubPath="ag/vwaf_integrated/guid-4e34476b-c2ac-408a-a477-41c4119ed487-output_low_277x277.jpg" showCaption="false" indent="1"} ::Image[]{src="https://api.archbee.com/api/optimize/wxZG1KsS4xNkVZYoiu_o9/Cu6mO5UHlTvS-QYn1bgFk_guid-146fbb13-60d9-4028-8874-4a0648cbc03a-outputlow275x275.jpg" position="flex-start" size="28" width="275" height="275" initialPath="guid-146fbb13-60d9-4028-8874-4a0648cbc03a-output_low_275x275.jpg" githubPath="ag/vwaf_integrated/guid-146fbb13-60d9-4028-8874-4a0648cbc03a-output_low_275x275.jpg" showCaption="false" indent="1"} ::Image[]{src="https://api.archbee.com/api/optimize/wxZG1KsS4xNkVZYoiu_o9/OKESwUbEk0UXq1DkGcjZ__guid-6eb660eb-0b00-4a13-ad6b-80454ea49e44-outputlowpng285x285.jpg" position="flex-start" size="28" width="285" height="285" initialPath="guid-6eb660eb-0b00-4a13-ad6b-80454ea49e44-output_low.png_285x285.jpg" githubPath="ag/vwaf_integrated/guid-6eb660eb-0b00-4a13-ad6b-80454ea49e44-output_low.png_285x285.jpg" showCaption="false" indent="1"} **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: :::hint{type="info"} 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. | 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](docId\:DwQFfCb94WbYIZMdVipbH)) | | 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](docId:3VcG4M4PeYN4G5D4tCsuL)). | | 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](docId\:y0rU8iFsj9WfiMsLcgdzA), and from being listed in [Reports](docId:1NE-_LwJkIvGOrOiLMowI). 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](docId\:cLT-s9nkkyQGiZHDYfFzU)). | :::hint{type="info"} For details regarding entries added to the log file by this handler, see the relevant section in [Entries in Application-Specific Log Files](docId\:crbZcvVfRSdEXrvik4Qio). :::