--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_http_cookie/README.markdown Thu May 24 13:25:13 2018 +0100
@@ -0,0 +1,64 @@
+---
+labels:
+- Stage-Alpha
+...
+
+Introduction
+============
+
+This is an experimental authentication module that does an asynchronous
+HTTP call to verify username and password.
+
+This is a (possibly temporary) fork of mod_http_auth_async that adds
+support for authentication using a cookie and SASL EXTERNAL.
+
+Details
+=======
+
+When a user attempts to authenticate to Prosody, this module takes the
+username and password and does a HTTP GET request with [Basic
+authentication][rfc7617] to the configured `http_auth_url`.
+
+Configuration
+=============
+
+``` lua
+VirtualHost "example.com"
+ authentication = "http_auth_cookie"
+ http_auth_url = "http://example.com/auth"
+ http_cookie_auth_url = "https://example.com/testcookie.php?user=$user"
+```
+
+Cookie Authentication
+=====================
+
+It is possible to link authentication to an existing web application. This
+has the benefit that the user logging into the web application in their
+browser will automatically log them into their XMPP account.
+
+There are some prerequisites for this to work:
+
+ - The BOSH or Websocket requests must include the application's cookie in
+ the headers sent to Prosody. This typically means the web chat code needs
+ to be served from the same domain as the web application.
+
+ - The web application must have a URL that returns 200 OK when called with
+ a valid cookie, and returns a different status code if the cookie is invalid
+ or not currently logged in.
+
+ - The XMPP username for the user must be passed to Prosody by the client, or
+ returned in the 200 response from the web application.
+
+Set `http_cookie_auth_url` to the web application URL that is used to check the
+cookie. You may use the variables `$host` for the XMPP host and `$user` for the
+XMPP username.
+
+If the `$user` variable is included in the URL, the client must provide the username
+via the "authzid" in the SASL EXTERNAL authentication mechanism.
+
+If the `$user` variable is *not* included in the URL, Prosody expects the web application's response to be the username instead, as UTF-8 text/plain.
+
+Compatibility
+=============
+
+Requires Prosody trunk