prosody-modules
06fbbd45ba75
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 @ 6302:06fbbd45ba75

mod_cloud_notify: Readme: fix links and labels that were removed in the last commit diff --git a/mod_cloud_notify/README.md b/mod_cloud_notify/README.md --- a/mod_cloud_notify/README.md +++ b/mod_cloud_notify/README.md @@ -1,3 +1,9 @@ +---- +-labels: +-- 'Stage-Beta' +-summary: 'XEP-0357: Cloud push notifications' +---- + # Introduction This module enables support for sending "push notifications" to clients @@ -32,15 +38,15 @@ notification to your device. When your d it will display it or wake up the app so it can connect to XMPP and receive any pending messages. -This protocol is described for developers in \[XEP-0357: Push -Notifications\]. +This protocol is described for developers in [XEP-0357: Push +Notifications]. -For this module to work reliably, you must have \[mod_smacks\], -\[mod_mam\] and \[mod_carbons\] also enabled on your server. +For this module to work reliably, you must have [mod_smacks], +[mod_mam] and [mod_carbons] also enabled on your server. Some clients, notably Siskin and Snikket iOS need some additional extensions that are not currently defined in a standard XEP. To support -these clients, see \[mod_cloud_notify_extensions\]. +these clients, see [mod_cloud_notify_extensions]. # Configuration @@ -58,18 +64,18 @@ these clients, see \[mod_cloud_notify_ex # Internal design notes App servers are notified about offline messages, messages stored by -\[mod_mam\] or messages waiting in the smacks queue. The business rules +[mod_mam] or messages waiting in the smacks queue. The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. -To cooperate with \[mod_smacks\] this module consumes some events: +To cooperate with [mod_smacks] this module consumes some events: `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. These events allow this module to send out notifications for messages received while the session is hibernated by -\[mod_smacks\] or even when smacks acknowledgements for messages are +[mod_smacks] or even when smacks acknowledgements for messages are delayed by a certain amount of seconds configurable with the -\[mod_smacks\] setting `smacks_max_ack_delay`. +[mod_smacks] setting `smacks_max_ack_delay`. The `smacks_max_ack_delay` setting allows to send out notifications to clients which aren't already in smacks hibernation state (because the
author Menel <menel@snikket.de>
date Fri, 13 Jun 2025 10:44:37 +0200
parent 4723:0a0334a3a784
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
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
3 This module externalizes MUC authorization via HTTP.
4296
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`
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
5 with the user's bare jid (`userJID`), the MUC jid (`mucJID`) and the user's nickname (`nickname`) as GET parameters.
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
6 Example:
4695
4b3f054666e6 mod_muc_http_auth: External auth services might need to check on the nickname as well
Seve Ferrer <seve@delape.net>
parents: 4322
diff changeset
7 `https://www.prosody.im/users/can-join/?userJID=romeo@example.com&mucJID=teaparty@chat.example.com&nickname=Romeo`
4296
08138de4cb88 Prosodoy module to externalize MUC authorization via HTTP
Seve Ferrer <seve@delape.net>
parents:
diff changeset
8
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
9 This allows an external service to decide whether a user is authorized to join a MUC or not.
4296
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
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
42 | Name | Description | Default |
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
43 |------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------|
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
44 | muc_http_auth_url | URL of the external HTTP service to which send `userJID`, `mucJID` and `nickname` in a GET request | "" |
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
45 | muc_http_auth_enabled_for | A map of user hostnames to an array of MUC names (node part) to enable this module for. To enable for all hostnames, use `"all"` as key. | nil |
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
46 | muc_http_auth_disabled_for | A map of user hostnames to an array of MUC names (node part) to disable this module for. To disable for all hostnames, use `"all"` as key. | nil |
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
47 | muc_http_auth_insecure | Disable certificate verification for request. Only intended for development of the external service. | false |
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
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 ```
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
53 -- muc_http_auth_enabled_for = {["all"] = {"teaparty"}}
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
54 -- muc_http_auth_disabled_for = {["all"] = {"teaparty"}}
4296
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
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
58 Note: Use the node part of the MUC jid for these lists. Example:
4296
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:
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
61 `muc_http_auth_enabled_for = {["all"] = {"teaparty@rooms.example.net"}}`
4296
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:
4723
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
64 `muc_http_auth_enabled_for = {["all"] = {"teaparty"}}`
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
65
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
66 It's also possible to disable/enable checking for a particular host, for example:
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
67
0a0334a3a784 mod_muc_http_auth: Allow for enabling/disabling per user host
JC Brand <jc@opkode.com>
parents: 4695
diff changeset
68 `muc_http_auth_enabled_for = {["jabber.org"] = {"teaparty"}, ["prosody.org] = {"orchard"}}`