prosody-modules
3f3b672b7616
mod_muc_http_auth/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_muc_http_auth/README.md @ 4300:3f3b672b7616

mod_vcard_muc: Pass room object around instead of JID, hopefully fixing traceback More efficient to pass the object around instead of using the JID and looking up the object when needed. It seems in some (undetermined) cases get_room_from_jid(room.jid) is nil.
author Matthew Wild <mwild1@gmail.com>
date Tue, 15 Dec 2020 10:49:11 +0000
parent 4296:08138de4cb88
child 4303:d261233f7ced
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 |
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
48
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 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
51 ```
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
52 -- muc_http_auth_enabled_for = {"teaparty"}
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
53 -- muc_http_auth_disabled_for = {"teaparty"}
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
54 ```
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
55 If none or both are found, all rooms in the MUC component will have this module enabled.
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
56
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
57 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
58
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
59 Wrong:
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
60 `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
61
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
62 Correct:
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
63 `muc_http_auth_enabled_for = {"teaparty"}`