Mercurial > prosody-modules
annotate mod_http_muc_kick/README.md @ 5615:308b5b117379
mod_http_oauth2: Hint at future deprecation of resource owner password grant
It is strongly discouraged by all the modern OAuth 2.0 (and 2.1) documents.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Fri, 21 Jul 2023 00:38:04 +0200 (17 months ago) |
parents | 9fc52ccfb445 |
children |
rev | line source |
---|---|
4642
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
1 # Introduction |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
2 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
3 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
4 This module allows kicking users out of MUCs via HTTP. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
5 It can be used in combination with [mod_muc_http_auth](https://modules.prosody.im/mod_muc_http_auth.html) as a complement to externalize MUC access. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
6 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
7 This module expects a JSON payload with the following keys: |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
8 * `nickname` Mandatory. The nickname of the user to be kicked. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
9 * `muc` Mandatory. The JID of the muc to kick the user from. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
10 * `reason` Optional. A comment explaining the reason of the kick (More details https://xmpp.org/extensions/xep-0045.html#example-91). |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
11 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
12 Example: |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
13 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
14 { |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
15 nickname: "Bob", |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
16 muc: "snuggery@chat.example.org", |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
17 } |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
18 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
19 If the user was kicked successfuly, the module will return a 200 status code. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
20 Otherwise, the according status code will be returned in the response, as well as a JSON payload providing an error message. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
21 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
22 { |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
23 error: "Missing nickname and/or MUC" |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
24 } |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
25 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
26 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
27 The path this module listens on is `/muc_kick`. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
28 Example of a request to kick `Bob` from the `snuggery@chat.example.org` MUC using cURL: |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
29 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
30 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
31 curl --header "Content-Type: application/json" \ |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
32 --request POST \ |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
33 -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \ |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
34 --data '{"nickname":"Bob","muc":"snuggery@chat.example.org"}' \ |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
35 http://chat.example.org:5280/muc_kick |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
36 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
37 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
38 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
39 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
40 # Configuring |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
41 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
42 ## Enabling |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
43 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
44 ``` {.lua} |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
45 Component "chat.example.org" "muc" |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
46 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
47 modules_enabled = { |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
48 "http_muc_kick"; |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
49 } |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
50 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
51 http_muc_kick_authorization_header = "Basic YWxhZGRpbjpvcGVuc2VzYW1l" -- Check the Settings section below |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
52 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
53 ``` |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
54 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
55 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
56 ## Settings |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
57 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
58 |Name |Description |Default | |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
59 |-----|------------|--------| |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
60 |http_muc_kick_authorization_header| Value of the Authorization header expected by every request when trying to kick a user. Example: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`| nil | |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
61 |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
62 Even though there is no check on whether the Authorization header provided is a valid one, |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
63 please be aware that if `http_muc_kick_authorization_header` is nil, the module will not load as a reminder that some authorization should be enforced for this module. |
9fc52ccfb445
mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff
changeset
|
64 |