[Kolab-devel] XMPP integration in Kolab web client

[Thomas Brüderli]

Dear all

I'd like to introduce you to a possible path how to integrate XMPP into
the Kolab web client for those how have a Jabber server running along
with their Kolab installation.

This is what you need to get started:

* A Kolab 3.1 installation with Roundcube 1.0
* A Jabber server authenticating against the same LDAP service as Kolab
* The converse.js plugin for Roundcube [1]
* BOSH support enabled or a BOSH proxy such as punjab [2]


1. Install the converse.js plugin
---------------------------------

So first, you should install and enable the converse.js plugin for
Roundcube. Clone the git repository from [1] and symlink it to
/usr/share/roundcubemail/plugins/converse. Then cd into that directory
and create a local config file by copying the sample config:

  cp config.inc.php.dist config.inc.php

Now edit the config.inc.php file according to your setup. Consider
adjusting the following options:

$rcmail_config['converse_xmpp_bosh_prebind_url'] =
'http://localhost:5280/http-bind';

$rcmail_config['converse_xmpp_bosh_url'] = '/http-bind';

$rcmail_config['converse_xmpp_hostname'] = function($args) {
  list($user,$host) = explode('@', $args['user']);
  return $host;
};

The 'converse_xmpp_hostname' can also be a hard-coded string value if
you run a single-domain setup.


1a. XMPP Authentication using UIDs
----------------------------------

If your Jabber service authenticates on Kolab's LDAP directory with the
user's UID, you need to adjust the converse plugin configuration
accordingly. In a Kolab environment, Roundcube holds the user's UID in
session data and this needs to be used as XMPP username for the
server-side pre-binding. Your config should then look like this:

$rcmail_config['converse_xmpp_username'] = function($args) {
  return $_SESSION['kolab_uid'];
};

Read the full story here: [3].


2. Setup an XMPP connection manager
-----------------------------------

Converse.js uses HTTP as protocol to communicate with the web server.
Access is furthermore restricted to the host that serves the web client.
If your Jabber server already supports BOSH and runs on the same host as
the web client, you should be fine with the default setup.

Otherwise, please read [4] to find out how to overcome cross-domain
request restrictions with either CORS or using a proxy that forwards the
XMPP HTTP requests.

I managed to connect the web server with the XMPP service using the
punjab BOSH proxy [2]. Simple HTTP proxy configurations with Apache or
Nginx are also explained in [4] are the preferable way if your Jabber
server already supports BOSH.


3. Debugging/Logging
--------------------

The Roundcube converse plugin has some limited debugging facilities.
Enable it in config with

  $rcmail_config['converse_xmpp_devel_mode'] = true;

The default pre-binding library only provides debug data over FirePHP.
You can switch to the old library that will write the full XMPP payload
into /var/log/roundcubemail/xmpp by setting

  $rcmail_config['converse_xmpp_old_style_prebind'] = true;

This, however, is limited to PLAIN authentication only.

For client-side debugging, open the browser's console to see the debug
output from converse.js

End of Setup.

Here's a screenshot of how the integration will look like:
http://i.imgur.com/fwVcIK9.png

As you can see from the directions above, the installation and setup
part of the Jabber server in conjunction with Kolab is not covered yet.
So if somebody has already done that or is willing to dig into this, any
feedback is much appreciated.

It would be nice to have out-of-the-box XMPP for Kolab.org 3.2. The XMPP
integration preferably would become part of the Kolab setup routine,
namely pykolab. Extending pykolab is quite easy. There's already a set
of different setup modules that can be used as an example for adding an
xmpp module [5].

I'd be happy to receive contributions for that!
And if you need more hints or get stuck, I'm willing to help out.

Kind regards,
Thomas


[1] https://github.com/priyadi/roundcube-converse.js-xmpp-plugin/
[2] https://github.com/twonds/punjab
[3] https://github.com/priyadi/roundcube-converse.js-xmpp-plugin/issues/6
[4] https://conversejs.org/docs/html/index.html#connection-manager
[5] http://git.kolab.org/pykolab/tree/pykolab/setup