cookie auth: allow for custom login logic in fail handler

1 files changed, 7 insertions, 2 deletions

diff --git a/readme.md b/readme.md
index 7508767..6145dff 100644
--- a/readme.md
+++ b/readme.md
@@ -164,7 +164,11 @@ themselves; in that case the request is passed on.
     come from. For successful logins two cookies are set: `gnix_username`
     containing the username and `gnix_auth` containing an opaque
     authentification token. The `gnix_username` cookie is authentificated by
-    gnix and can therefore be used by applications.
+    gnix and can therefore be used by applications. Alternatively a login may be
+    implemented by returning the `gnix-login-success` header with a username as
+    the value from the `fail` handler, which is handled like a sucessful login
+    for that user. This method can be useful for implementing custom login logic
+    like OTP login or a CAPTCHA.
   - `users`: list of valid logins (credentials)
   - `expire`: seconds before logins expire; not setting this option keeps the
     login valid forever on the server but cleared after the session on the
@@ -176,7 +180,8 @@ themselves; in that case the request is passed on.
   - `fail`: a module to handle the request when a user is not authorized. This
     could show an HTML form prompting the user to log in. An implementation of
     such a form is provided with the distribution of this software, usually in
-    `/usr/share/gnix/login.html` (module)
+    `/usr/share/gnix/login.html`. It can return the `gnix-login-success` header,
+    see above. (module)
 
 - **module `switch`**
   - Decides between two possible routes based on a condition.