prosody-modules
d611ed13df7e
mod_auth_http/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_auth_http/README.md @ 6209:d611ed13df7e

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