Mercurial > prosody-modules

annotate mod_auth_http_cookie/README.markdown @ 5668:ecfd7aece33b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_measure_modules: Report module statuses via OpenMetrics Someone in the chat asked about a health check endpoint, which reminded me of mod_http_status, which provides access to module statuses with full details. After that, this idea came about, which seems natural. As noted in the README, it could be used to monitor that critical modules are in fact loaded correctly. As more modules use the status API, the more useful this module and mod_http_status becomes.
author Kim Alvefur <zash@zash.se>
date Fri, 06 Oct 2023 18:34:39 +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