How to install Prosody using Tiki for its userlist

Prosody is a lightweight and modular XMPP (Jabber) server.

This page describes how an instance of Prosody can be set up in such a way that it will make use of the Tiki database as its identity provider (IdP) for:

Users
Groups
Authentication

It also shows how to expose anonymous chat for visitors (via Converse.js), and auto-join registered Tiki users to specific group chatrooms.

Note that this is a specialized setup, and comes with some challenges.

Preparation / Assumptions

A working instance of Tiki is available.

This guide assumes Tiki stores its own users, groups and permissions in its database (default). It has not been tested with setups using LDAP, Shibboleth, etc.

Prosody is installed on GNU/Linux (Debian/Ubuntu recommended).

Alternatives include Windows Subsystem for Linux and Docker

Domains used in this guide:
- xmpp.example.org → registered users (authenticated via Tiki)
- guest.example.org → anonymous visitors
- conference.example.org → MUC component (group chatrooms)
DNS (A/AAAA + SRV) and Let’s Encrypt certificates are set up for these hosts.
An administrative account in Tiki is available.

Install Prosody

Obtain and install Prosody from your package manager or the official repository.
Latest version (at time of writing): 13.0.2.

Debian/Ubuntu:

bash

sudo apt update
sudo apt install prosody
sudo systemctl enable --now prosody

Verify installation:

bash

sudo prosodyctl check config
sudo prosodyctl about

Common pitfalls :

Prosody was unable to find the configuration file

→ Ensure /etc/prosody/prosody.cfg.lua exists and is readable. Always run commands with sudo.

unexpected symbol near '`'

→ Remove stray characters from the config file.

Always restart after editing:

bash

sudo systemctl restart prosody
sudo systemctl status prosody

TLS Certificates

Generate development certificates:

bash

sudo prosodyctl cert generate xmpp.example.org
sudo prosodyctl cert generate guest.example.org
sudo prosodyctl cert generate conference.example.org

Or use Let’s Encrypt for production:

bash

sudo apt install certbot
sudo certbot certonly --standalone \
  -d xmpp.example.org \
  -d guest.example.org \
  -d conference.example.org
sudo prosodyctl --root cert import /etc/letsencrypt/live

Verify:

bash

sudo prosodyctl check certs

Expected output:

Certificate found for xmpp.example.org
Certificate found for guest.example.org
Certificate found for conference.example.org

More details: Prosody Certificate Documentation

Enable required modules

In /etc/prosody/prosody.cfg.lua under modules_enabled add:

lua

modules_enabled = {
    "bosh";        -- HTTP Bind
    "websocket";   -- XMPP over WebSockets
    "http";        -- HTTP endpoints
    "limits";      -- Anti-abuse limits
    "csi_simple";  -- Client state indication
    "blocklist";   -- User blocklist
    "smacks";      -- Stream resumption
    "ping";        -- Keepalive pings
}

⚠️ Note: muc and muc_mam are not enabled globally here — they must be loaded in a Component block, e.g.:

lua

Component "conference.localhost" "muc"
    modules_enabled = { "muc_mam" }

Note: For a full-featured XMPP server, you may also enable additional modules such as disco, roster, pep, vcard, etc. See Prosody modules documentation

Configure VirtualHosts and MUC Component

Prosody requires explicit VirtualHost and Component definitions for different roles:

xmpp.example.org → registered users (authenticated via Tiki)
guest.example.org → anonymous visitors (via Converse.js)
conference.example.org → group chatrooms (MUC)

Steps

Edit Prosody configuration:

bash

sudo nano /etc/prosody/prosody.cfg.lua

Add the following blocks:

lua

-- Global
consider_websocket_secure = true
consider_bosh_secure = true

-- VirtualHost for registered users (later connected with Tiki IdP)
VirtualHost "xmpp.localhost"
    enabled = true
    ssl = {
        key = "/etc/prosody/certs/xmpp.localhost.key";
        certificate = "/etc/prosody/certs/xmpp.localhost.crt";
    }

    -- 🔹 Auth via Tiki (mod_auth_http)
    authentication = "http"
    http_auth_url = "http://localhost/tiki/tiki-xmpp-auth.php"
    http_auth_credentials = "prosody:MySecret123!"
    c2s_require_encryption = false

-- VirtualHost for anonymous visitors
VirtualHost "guest.localhost"
    authentication = "anonymous"
    ssl = {
        key = "/etc/prosody/certs/guest.localhost.key";
        certificate = "/etc/prosody/certs/guest.localhost.crt";
    }
   c2s_require_encryption = false

-- Multi-User Chat component (chatrooms)
Component "conference.localhost" "muc"
    modules_enabled = { "muc_mam" } -- Archive chat history
    ssl = {
        key = "/etc/prosody/certs/conference.localhost.key";
        certificate = "/etc/prosody/certs/conference.localhost.crt";
    }

    -- 🔹 Allow anyone (including guest.localhost) to join
    muc_room_default_public = true
    muc_room_default_members_only = false
    muc_room_default_allow_anonymous = true

Replace SHARED_SECRET with the value configured in Tiki preferences.

Validate configuration:

bash

sudo prosodyctl check config
sudo systemctl restart prosody

For more : https://prosody.im/doc/configure

Test endpoints

bash

curl -I http://xmpp.example.org:5280/http-bind
curl -I http://xmpp.example.org:5280/xmpp-websocket

Expected: HTTP/1.1 200 OK

Check BOSH in browser
Open in your browser:
http://localhost:5280/http-bind — for local/dev only

You should see:

Note

Replace xmpp.example.org with your actual domain.
If you are only testing in a local lab, use xmpp.localhost, guest.localhost, and conference.localhost

Test with Gajim

1. Install Gajim:

bash

sudo apt install gajim -y

2. Connect as anonymous:
- Add new account
- Choose Sign up Anonymously
- Server: guest.example.org (or guest.localhost )
→ You should see a green status as anon@guest....

3. Create a test registered user (for lab/testing):

bash

sudo prosodyctl register testuser xmpp.example.org mypassword

- In Gajim → Add Account → JID = testuser@xmpp.example.org, password = mypassword

(Skip this step if you will connect via Tiki IdP instead of local Prosody accounts.)

4. Join or create a groupchat:
- In Gajim, click + → Join Group Chat
- Room: support
- Server: conference.example.org (or conference.localhost in local)
- You join support@conference....

For more details on configuration see: https://prosody.im/doc/configure

Configure Tiki (Admin → XMPP)

Section	Preference	Example value
Common (Openfire & Prosody)	XMPP MUC Domain	`conference.example.org`
	XMPP BOSH URL (http-bind)	`http://localhost:5280/http-bind` (local) `https://example.org/http-bind/` (production)
Prosody (HTTP Auth)	XMPP domain for registered users	`xmpp.localhost` (local) `xmpp.example.org` (production)
	XMPP domain for anonymous visitors	`guest.localhost` (local) `guest.example.org` (production)
	XMPP WebSocket URL	`ws://localhost:5280/xmpp-websocket` (local) `wss://example.org/xmpp-websocket` (production)
	Default anonymous chat room	`support@conference.example.org`
	Default registered chat room	`registered@conference.example.org`
	Mapping Tiki groups to chat rooms	`json { "Registered": "registered@conference.example.org", "Translators": "translators@conference.example.org" }`
	Auto-join strategy	by-groups (recommended)
	XMPP shared secret (HTTP auth)	(same secret as in Prosody config)
	CORS allowed origins (comma-separated)	`https://xmpp.localhost,https://guest.localhost` (local) `https://tiki.example.org` (production)
ConverseJS options (common)	Always Load ConverseJS	Enable ✅
	ConverseJS Debug Mode	Enable only for debugging
	ConverseJS Extra Settings	Optional JSON, e.g. `{ "show_controlbox_by_default": true }`

User Stories

1. Alice (anonymous visitor):
  She is is not registered. She sees the Converse.js pop up and she asks a question.
  Note:
  By default, wiki pages are cached, so the popup will not appear for anonymous users. To fix this:

Enable feature_wiki_icache (Individual wiki cache) in Admin search.
Edit the target wiki page.
In Page Properties, set Cache duration to 0.

2. Bob (registered user): Is automatically added to the Registered group and the associated chatroom.
3. Charlie (translator): Is also added to the Translators chatroom in addition to the Registered one.
4. Dan (geek): Uses his own external XMPP JID while still joining group chatrooms.
5. Eve (administrator): Uses Gajim (desktop XMPP client) to answer queries from anonymous visitors.