prosody-modules: mod_muc_http_auth/README.md annotate

annotate mod_muc_http_auth/README.md @ 5061:e44b868cc575

mod_storage_appendmap: Fix keyvalue writes store_raw() takes a filename, unlike most other datamanager functions that take a series of path components, leading to this bug where it would write the hostname into a file named after the first argument (commonly a username) in the working directory.

author	Kim Alvefur <zash@zash.se>
date	Sun, 09 Oct 2022 21:35:18 +0200
parents	0a0334a3a784
children

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"}}`

Mercurial > prosody-modules

annotate mod_muc_http_auth/README.md @ 5061:e44b868cc575