annotate mod_auth_http_cookie/README.markdown @ 4569:9cbdb60e21f2

mod_muc_bot: Add Compatibility section to README
author Kim Alvefur <zash@zash.se>
date Mon, 24 May 2021 16:36:35 +0200
parents bae7b0a002ef
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3037
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - Stage-Alpha
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 ...
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6 Introduction
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 ============
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 This is an experimental authentication module that does an asynchronous
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 HTTP call to verify username and password.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 This is a (possibly temporary) fork of mod_http_auth_async that adds
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 support for authentication using a cookie and SASL EXTERNAL.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 Details
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 =======
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 When a user attempts to authenticate to Prosody, this module takes the
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 username and password and does a HTTP GET request with [Basic
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 authentication][rfc7617] to the configured `http_auth_url`.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 Configuration
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 =============
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 ``` lua
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 VirtualHost "example.com"
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 authentication = "http_auth_cookie"
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 http_auth_url = "http://example.com/auth"
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 http_cookie_auth_url = "https://example.com/testcookie.php?user=$user"
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 ```
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 Cookie Authentication
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 =====================
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 It is possible to link authentication to an existing web application. This
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 has the benefit that the user logging into the web application in their
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 browser will automatically log them into their XMPP account.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 There are some prerequisites for this to work:
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 - The BOSH or Websocket requests must include the application's cookie in
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 the headers sent to Prosody. This typically means the web chat code needs
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 to be served from the same domain as the web application.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 - The web application must have a URL that returns 200 OK when called with
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 a valid cookie, and returns a different status code if the cookie is invalid
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 or not currently logged in.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 - The XMPP username for the user must be passed to Prosody by the client, or
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 returned in the 200 response from the web application.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 Set `http_cookie_auth_url` to the web application URL that is used to check the
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 cookie. You may use the variables `$host` for the XMPP host and `$user` for the
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 XMPP username.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 If the `$user` variable is included in the URL, the client must provide the username
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 via the "authzid" in the SASL EXTERNAL authentication mechanism.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 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.
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 Compatibility
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 =============
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63
bae7b0a002ef mod_auth_http_cookie: Possibly temporary fork of mod_http_auth_async that adds cookie auth support
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 Requires Prosody trunk