Mercurial > prosody-modules

annotate mod_auth_http/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 1da63fe35ef3
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4157
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - Stage-Alpha
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: "Authenticate users against an external HTTP API"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 # Overview
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 This authentication module allows Prosody to authenticate users against
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 an external HTTP service.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 # Configuration
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 ``` lua
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 VirtualHost "example.com"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 authentication = "http"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 http_auth_url = "http://example.com/auth"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 If the API requires Prosody to authenticate, you can provide static
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 credentials using HTTP Basic authentication, like so:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 http_auth_credentials = "prosody:secret-password"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 # Developers
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
4158
df1e0465ff81 mod_auth_http: Fix unfinished sentence in
Matthew Wild <mwild1@gmail.com>
parents: 4157
diff changeset
29 This section contains information for developers who wish to implement a
df1e0465ff81 mod_auth_http: Fix unfinished sentence in
Matthew Wild <mwild1@gmail.com>
parents: 4157
diff changeset
30 HTTP service that Prosody can use for authentication.
4157
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 ## Protocol
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 Prosody will make a HTTP request to the configured API URL with an
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 appended `/METHOD` where `METHOD` is one of the methods described below.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 GET methods must expect a series of URL-encoded query parameters, while
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 POST requests will receive an URL-encoded form (i.e.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 `application/x-www-form-urlencoded`).
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 ## Parameters
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 user
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 : The username, e.g. `stephanie` for the JID `stephanie@example.com`.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 server
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 : The host part of the user's JID, e.g. `example.com` for the JID
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 `stephanie@example.com`.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 pass
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 : For methods that verify or set a user's password, the password will
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 be supplied in this parameter, otherwise it is not set.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 ## Methods
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 The only mandatory methods that the service must implement are `check_password`
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 and `user_exists`. Unsupported methods should return a HTTP status code
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 of `501 Not Implemented`, but other error codes will also be handled by
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 Prosody.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60
4594
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
61 Method HTTP method Success codes Error codes Response
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
62 -------- ---- --- ----------------- -----------------------------------------------------------------
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
63 register POST 201 409 (user exists)
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
64 check\_password GET 200 A text string of `true` if the user exists, or `false` otherwise.
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
65 user\_exists GET 200 A text string of `true` if the user exists, or `false` otherwise.
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
66 set\_password POST 200, 201 or 204
1da63fe35ef3 mod_auth_http: Format README better
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 4158
diff changeset
67 remove\_user POST 200, 201 or 204
4157
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 ## Examples
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 With the following configuration:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 authentication = "http"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 http_auth_url = "https://auth.example.net/api"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 If a user connects and tries to log in to Prosody as "romeo@example.net"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 with the password "iheartjuliet", Prosody would make the following HTTP
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 request:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82 https://auth.example.net/api/check_password?user=romeo&server=example.net&pass=iheartjuliet
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 # Compatibility
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 Requires Prosody 0.11.0 or later.