Software /
code /
prosody-modules
Annotate
mod_muc_http_auth/README.md @ 4692:37232302dfb9
mod_muc_require_tos: Prevent a traceback when receiving a message with occupant being nil
author | Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> |
---|---|
date | Thu, 16 Sep 2021 22:47:52 +0200 |
parent | 4322:9606e7a63a69 |
child | 4695:4b3f054666e6 |
rev | line source |
---|---|
4296
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
1 # Introduction |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
2 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
3 This module externalizes MUC authorization via HTTP. |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
4 Whenever a user wants to join a MUC, an HTTP GET request is made to `authorization_url` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
5 with the user bare jid (`userJID`) and the MUC jid (`mucJID`) as GET parameters. |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
6 Example: |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
7 `https://www.prosody.im/users/can-join/?userJID=romeo@example.com&mucJID=teaparty@chat.example.com` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
8 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
9 This allows an external service to decide whether a user is authorized to join a MUC or not. |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
10 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
11 When a user is authorized to join a MUC, this module expects the following JSON payload: |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
12 ``` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
13 { |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
14 allowed: true, |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
15 error: "", |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
16 } |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
17 ``` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
18 Otherwise, either the user not being authorized or some failure in the external service: |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
19 ``` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
20 { |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
21 allowed: false, |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
22 error: "Some error message to be displayed in this module's logs", |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
23 } |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
24 ``` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
25 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
26 # Configuring |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
27 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
28 ## Enabling |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
29 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
30 ``` {.lua} |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
31 Component "rooms.example.net" "muc" |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
32 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
33 modules_enabled = { |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
34 "muc_http_auth"; |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
35 } |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
36 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
37 ``` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
38 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
39 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
40 ## Settings |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
41 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
42 |Name |Description |Default | |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
43 |-----|------------|--------| |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
44 |muc_http_auth_url| URL of the external HTTP service to which send `userJID` and `mucJID` in a GET request | "" | |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
45 |muc_http_auth_enabled_for| List of MUC names (node part) to enable this module for | nil | |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
46 |muc_http_auth_disabled_for| List of MUC names (node part) to disable this module for | nil | |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
47 |muc_http_auth_insecure| Disable certificate verification for request. Only intended for development of the external service. | false | |
4322
9606e7a63a69
mod_mucc_http_auth: Provide Authorization header setting for deployments behind a login
Seve Ferrer <seve@delape.net>
parents:
4303
diff
changeset
|
48 |muc_http_auth_authorization_header| Value of the Authorization header if requested by the external HTTP service. Example: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`| nil | |
4296
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
49 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
50 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
51 This module can be enabled/disabled for specific rooms. Only one of the following settings must be set. |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
52 ``` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
53 -- muc_http_auth_enabled_for = {"teaparty"} |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
54 -- muc_http_auth_disabled_for = {"teaparty"} |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
55 ``` |
4303
d261233f7ced
Improve UX by providing defaults users expect
Seve Ferrer <seve@delape.net>
parents:
4296
diff
changeset
|
56 If none is set, all rooms in the MUC component will have this module enabled. |
4296
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
57 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
58 Note: Use the node part of the MUC jid for these lists. Example: |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
59 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
60 Wrong: |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
61 `muc_http_auth_enabled_for = {"teaparty@rooms.example.net"}` |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
62 |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
63 Correct: |
08138de4cb88
Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
64 `muc_http_auth_enabled_for = {"teaparty"}` |