view mod_muc_http_auth/README.md @ 4651:8231774f5bfd

mod_cloud_notify_encrypted: Ensure body substring remains valid UTF-8 The `body:sub()` call risks splitting the string in the middle of a multi-byte UTF-8 sequence. This should have been caught by util.stanza validation, but that would have caused some havoc, at the very least causing the notification to not be sent. There have been no reports of this happening. Likely because this module isn't widely deployed among users with languages that use many longer UTF-8 sequences. The util.encodings.utf8.valid() function is O(n) where only the last sequence really needs to be checked, but it's in C and expected to be fast.
author Kim Alvefur <zash@zash.se>
date Sun, 22 Aug 2021 13:22:59 +0200
parents 9606e7a63a69
children 4b3f054666e6
line wrap: on
line source

# Introduction

This module externalizes MUC authorization via HTTP.  
Whenever a user wants to join a MUC, an HTTP GET request is made to `authorization_url`
with the user bare jid (`userJID`) and the MUC jid (`mucJID`) as GET parameters.  
Example:  
`https://www.prosody.im/users/can-join/?userJID=romeo@example.com&mucJID=teaparty@chat.example.com`

This allows an external service to decide whether a user is authorized to join a MUC or not.  

When a user is authorized to join a MUC, this module expects the following JSON payload:
```
{
    allowed: true,
    error: "",
}
```
Otherwise, either the user not being authorized or some failure in the external service:
```
{
    allowed: false,
    error: "Some error message to be displayed in this module's logs",
}
```

# Configuring

## Enabling

``` {.lua}
Component "rooms.example.net" "muc"

modules_enabled = {
    "muc_http_auth";
}

```


## Settings

|Name |Description |Default |
|-----|------------|--------|
|muc_http_auth_url| URL of the external HTTP service to which send `userJID` and `mucJID` in a GET request | "" |
|muc_http_auth_enabled_for| List of MUC names (node part) to enable this module for | nil |
|muc_http_auth_disabled_for| List of MUC names (node part) to disable this module for | nil |
|muc_http_auth_insecure| Disable certificate verification for request. Only intended for development of the external service. | false |
|muc_http_auth_authorization_header| Value of the Authorization header if requested by the external HTTP service. Example: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`| nil |


This module can be enabled/disabled for specific rooms. Only one of the following settings must be set.
```
-- muc_http_auth_enabled_for = {"teaparty"}
-- muc_http_auth_disabled_for = {"teaparty"}
```
If none is set, all rooms in the MUC component will have this module enabled.

Note: Use the node part of the MUC jid for these lists. Example:  

Wrong:
`muc_http_auth_enabled_for = {"teaparty@rooms.example.net"}`

Correct:
`muc_http_auth_enabled_for = {"teaparty"}`