Annotate

mod_http_muc_kick/README.md @ 5193:2bb29ece216b

mod_http_oauth2: Implement stateless dynamic client registration Replaces previous explicit registration that required either the additional module mod_adhoc_oauth2_client or manually editing the database. That method was enough to have something to test with, but would not probably not scale easily. Dynamic client registration allows creating clients on the fly, which may be even easier in theory. In order to not allow basically unauthenticated writes to the database, we implement a stateless model here. per_host_key := HMAC(config -> oauth2_registration_key, hostname) client_id := JWT { client metadata } signed with per_host_key client_secret := HMAC(per_host_key, client_id) This should ensure everything we need to know is part of the client_id, allowing redirects etc to be validated, and the client_secret can be validated with only the client_id and the per_host_key. A nonce injected into the client_id JWT should ensure nobody can submit the same client metadata and retrieve the same client_secret
author Kim Alvefur <zash@zash.se>
date Fri, 03 Mar 2023 21:14:19 +0100
parent 4642:9fc52ccfb445
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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