--- a/doc/admin_guide.txt	Fri Jun 11 18:09:21 2021 -0400
+++ b/doc/admin_guide.txt	Mon Jun 14 19:33:27 2021 -0400
@@ -208,7 +208,8 @@
    Authentication or cookie authentication. If you are running the web
    server (roundup-server) through another HTTP server (eg. apache or IIS)
    then that server may require HTTP Basic Authentication, and it will pass
-   the ``REMOTE_USER`` variable through to Roundup. If this variable is not
+   the ``REMOTE_USER`` variable (or variable defined using
+   http_auth_header) through to Roundup. If this variable is not
    present, then Roundup defaults to using its own cookie-based login
    mechanism.
 2. In email messages handled by roundup-mailgw, users are identified by the
@@ -228,6 +229,47 @@
 More information about how to customise your tracker's security settings
 may be found in the `customisation documentation`_.
 
+Configuring Authentication Header/Variable
+------------------------------------------
+
+The front end server running roundup can perform the user
+authentication. It pass the authenticated username to the backend in a
+variable. By default roundup looks for the ``REMOTE_USER`` variable
+This can be changed by setting the parameter ``http_auth_header`` in the
+``[web]`` section of the tracker's ``config.ini`` file. If the value
+is unset (the default) the REMOTE_USER variable is used.
+
+If you are running roundup using ``roundup-server`` behind a proxy
+that authenticates the user you need to configure ``roundup-server`` to
+pass the proper header to the tracker. By default ``roundup-server``
+looks for the ``REMOTE_USER`` header for the authenticated user.  You
+can copy an arbitrary header variable to the tracker using the ``-I``
+option to roundup-server (or the equivalent option in the
+roundup-server config file).
+
+For example to use the ``uid_variable`` header, two configuration
+changes are needed: First configure ``roundup-server`` to pass the
+header to the tracker using::
+
+  roundup-server -I uid_variable ....
+
+note that the header is passed exactly as supplied by the upstream
+server. It is **not** prefixed with ``HTTP_`` like other headers since
+you are explicitly whitelisting the header. Multiple comma separated
+headers can be passed to the ``-I`` option. These could be used in a
+detector or other tracker extensions, but only one header can be used
+by the tracker as an authentication header.
+
+To make the tracker honor the new variable changing the tracker
+``config.ini`` to read::
+
+  [web]
+  ...
+  http_auth_header = uid_variable
+
+At the time this is written, support is experimental. If you use it
+you should notify the roundup maintainers using the roundup-users
+mailing list.
 
 Tasks
 =====