Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

auth-request Test

auth-request allows you to add access control to your HTTP services based on a subrequest to a configured HAProxy backend. The workings of this Lua script are loosely based on the ngx_http_auth_request_module module for nginx.


  • HAProxy 1.8.4+ (2.2.0+ recommended)
    • Only the latest version of each HAProxy branch is supported.
  • USE_LUA=1 must be set at compile time.
  • haproxy-lua-http must be available within the Lua path.
    • A json library within the Lua path (dependency of haproxy-lua-http).
    • With HAProxy 2.1.3+ you can use the lua-prepend-path configuration option to specify the search path.


  1. Load this Lua script in the global section of your haproxy.cfg:

        # *snip*
        lua-prepend-path /usr/share/haproxy/?/http.lua # If haproxy-lua-http is saved as /usr/share/haproxy/haproxy-lua-http/http.lua
        lua-load /usr/share/haproxy/auth-request.lua
  2. Define a backend that is used for the subrequests:

    backend auth_request
        mode http
        server auth_request check
  3. Execute the subrequest in your frontend (as early as possible):

    frontend http
        mode http
        bind :::80 v4v6
        # *snip*
        #                             Backend name     Path to request
        http-request lua.auth-request auth_request     /is-allowed
  4. Act on the results:

    frontend http
        # *snip*
        http-request deny if ! { var(txn.auth_response_successful) -m bool }

Available Variables

auth-request uses HAProxy variables to communicate the results back to you. The var() sample fetch can be used to retrieve the variable contents.

The following list of variables may be set.

Set to true if the subrequest returns an HTTP status code in the 2xx range. false otherwise.
The HTTP status code of the subrequest. If the subrequest did not return a valid HTTP response the value will be 500.
The location response header of the subrequest.

This variable is only set if the HTTP status code of the subrequest indicates a redirect (i.e. 301, 302, 303, 307, or 308).

These variables store the subrequest’s response headers. The values of duplicate response headers will be merged with a comma.

HAProxy variables may only contain alphanumeric characters, the dot (.), and an underscore _. Any non-alphanumeric characters will be replaced with an underscore to be representable. If the response contains duplicate response headers after normalizing the header name the result for these headers will be undefined.

Normalization examples:


Please note: The scope of the response header variables is req compared to txn for the other variables. The contents will no longer be available during response processing to save memory. Copy the values of interest into a txn. variable if you need access them during response processing.

Inner Workings

The Lua script will make a HTTP request to the first server in the given backend that is either marked as UP or that does not have checks enabled. This allows for basic health checking of the auth-request backend. If you need more complex processing of the request forward the auth-request to a separate HAProxy frontend that performs the required modifications to the request and response.

The requested URL is the one given in the second parameter.

Any request headers will be forwarded as-is to the auth-request backend, with the exception of the content-length header which will be stripped, because the request body will not be forwarded.

Known limitations

  • The Lua script only supports basic health checking, without redispatching or load balancing of any kind.
  • The backend must not be using TLS.