prosody-modules
08138de4cb88
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

Comparison

mod_muc_http_auth/README.md @ 4296:08138de4cb88

Prosodoy module to externalize MUC authorization via HTTP
author Seve Ferrer <seve@delape.net>
date Sat, 12 Dec 2020 18:19:14 +0100
child 4303:d261233f7ced
comparison
equal deleted inserted replaced
4295:d44a8d3dd571 4296:08138de4cb88
1 # Introduction
2
3 This module externalizes MUC authorization via HTTP.
4 Whenever a user wants to join a MUC, an HTTP GET request is made to `authorization_url`
5 with the user bare jid (`userJID`) and the MUC jid (`mucJID`) as GET parameters.
6 Example:
7 `https://www.prosody.im/users/can-join/?userJID=romeo@example.com&mucJID=teaparty@chat.example.com`
8
9 This allows an external service to decide whether a user is authorized to join a MUC or not.
10
11 When a user is authorized to join a MUC, this module expects the following JSON payload:
12 ```
13 {
14 allowed: true,
15 error: "",
16 }
17 ```
18 Otherwise, either the user not being authorized or some failure in the external service:
19 ```
20 {
21 allowed: false,
22 error: "Some error message to be displayed in this module's logs",
23 }
24 ```
25
26 # Configuring
27
28 ## Enabling
29
30 ``` {.lua}
31 Component "rooms.example.net" "muc"
32
33 modules_enabled = {
34 "muc_http_auth";
35 }
36
37 ```
38
39
40 ## Settings
41
42 |Name |Description |Default |
43 |-----|------------|--------|
44 |muc_http_auth_url| URL of the external HTTP service to which send `userJID` and `mucJID` in a GET request | "" |
45 |muc_http_auth_enabled_for| List of MUC names (node part) to enable this module for | nil |
46 |muc_http_auth_disabled_for| List of MUC names (node part) to disable this module for | nil |
47 |muc_http_auth_insecure| Disable certificate verification for request. Only intended for development of the external service. | false |
48
49
50 This module can be enabled/disabled for specific rooms. Only one of the following settings must be set.
51 ```
52 -- muc_http_auth_enabled_for = {"teaparty"}
53 -- muc_http_auth_disabled_for = {"teaparty"}
54 ```
55 If none or both are found, all rooms in the MUC component will have this module enabled.
56
57 Note: Use the node part of the MUC jid for these lists. Example:
58
59 Wrong:
60 `muc_http_auth_enabled_for = {"teaparty@rooms.example.net"}`
61
62 Correct:
63 `muc_http_auth_enabled_for = {"teaparty"}`