Mercurial > prosody-modules

comparison mod_muc_http_auth/README.md @ 4723:0a0334a3a784

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_muc_http_auth: Allow for enabling/disabling per user host IMPORTANT: This is a breaking change. The `muc_http_auth_enabled_for` and `muc_http_auth_disabled_for` options are now maps (with user hosts as keys) and not sets.
author JC Brand <jc@opkode.com>
date Mon, 25 Oct 2021 15:58:16 +0200
parents 4b3f054666e6
children
comparison
equal deleted inserted replaced
4722:c5b1e9b8ccca 4723:0a0334a3a784
1 # Introduction 1 # Introduction
2 2
3 This module externalizes MUC authorization via HTTP. 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` 4 Whenever a user wants to join a MUC, an HTTP GET request is made to `authorization_url`
5 with the user's bare jid (`userJID`), the MUC jid (`mucJID`) and the user's nickname (`nickname`) as GET parameters. 5 with the user's bare jid (`userJID`), the MUC jid (`mucJID`) and the user's nickname (`nickname`) as GET parameters.
6 Example: 6 Example:
7 `https://www.prosody.im/users/can-join/?userJID=romeo@example.com&mucJID=teaparty@chat.example.com&nickname=Romeo` 7 `https://www.prosody.im/users/can-join/?userJID=romeo@example.com&mucJID=teaparty@chat.example.com&nickname=Romeo`
8 8
9 This allows an external service to decide whether a user is authorized to join a MUC or not. 9 This allows an external service to decide whether a user is authorized to join a MUC or not.
10 10
11 When a user is authorized to join a MUC, this module expects the following JSON payload: 11 When a user is authorized to join a MUC, this module expects the following JSON payload:
12 ``` 12 ```
13 { 13 {
14 allowed: true, 14 allowed: true,
37 ``` 37 ```
38 38
39 39
40 ## Settings 40 ## Settings
41 41
42 |Name |Description |Default | 42 | Name | Description | Default |
43 |-----|------------|--------| 43 |------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------|
44 |muc_http_auth_url| URL of the external HTTP service to which send `userJID`, `mucJID` and `nickname` in a GET request | "" | 44 | muc_http_auth_url | URL of the external HTTP service to which send `userJID`, `mucJID` and `nickname` in a GET request | "" |
45 |muc_http_auth_enabled_for| List of MUC names (node part) to enable this module for | nil | 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 |
46 |muc_http_auth_disabled_for| List of MUC names (node part) to disable this module for | nil | 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 |
47 |muc_http_auth_insecure| Disable certificate verification for request. Only intended for development of the external service. | false | 47 | muc_http_auth_insecure | Disable certificate verification for request. Only intended for development of the external service. | false |
48 |muc_http_auth_authorization_header| Value of the Authorization header if requested by the external HTTP service. Example: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`| nil | 48 | muc_http_auth_authorization_header | Value of the Authorization header if requested by the external HTTP service. Example: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=` | nil |
49 49
50 50
51 This module can be enabled/disabled for specific rooms. Only one of the following settings must be set. 51 This module can be enabled/disabled for specific rooms. Only one of the following settings must be set.
52 ``` 52 ```
53 -- muc_http_auth_enabled_for = {"teaparty"} 53 -- muc_http_auth_enabled_for = {["all"] = {"teaparty"}}
54 -- muc_http_auth_disabled_for = {"teaparty"} 54 -- muc_http_auth_disabled_for = {["all"] = {"teaparty"}}
55 ``` 55 ```
56 If none is set, all rooms in the MUC component will have this module enabled. 56 If none is set, all rooms in the MUC component will have this module enabled.
57 57
58 Note: Use the node part of the MUC jid for these lists. Example: 58 Note: Use the node part of the MUC jid for these lists. Example:
59 59
60 Wrong: 60 Wrong:
61 `muc_http_auth_enabled_for = {"teaparty@rooms.example.net"}` 61 `muc_http_auth_enabled_for = {["all"] = {"teaparty@rooms.example.net"}}`
62 62
63 Correct: 63 Correct:
64 `muc_http_auth_enabled_for = {"teaparty"}` 64 `muc_http_auth_enabled_for = {["all"] = {"teaparty"}}`
65
66 It's also possible to disable/enable checking for a particular host, for example:
67
68 `muc_http_auth_enabled_for = {["jabber.org"] = {"teaparty"}, ["prosody.org] = {"orchard"}}`