This is a simple module that provides a HTTP interface authenticated using basic access authentication for creating an authenticated BOSH session on behalf of other users.
This enables the complex BOSH handshake to be done behind the scenes and avoids transmitting the password to the client (only the SID and RID are used).
In practice a client can send a request for a warmed BOSH binding to a web service. The web service would then send a POST request to this ejabberd module to create the BOSH session - returning the JID, SID and RID. These details are handed back to the client and from here the client can communicate directly with the BOSH connection of ejabberd.
The POST request is comprised of:
- basic access authentication headers for a user specified as an admin on the acl
- jid parameter - this can either be a bare of full JID
- password parameter - the password for the above JID
and optional parts:
- language - This attribute specifies the default language of any human-readable XML character data sent or received during the session.
- wait - This attribute specifies the longest time (in seconds) that the connection manager is allowed to wait before responding to any request during the session. This enables the client to limit the delay before it discovers any network failure, and to prevent its HTTP/TCP connection from expiring due to inactivity.
- hold - This attribute specifies the maximum number of requests the connection manager is allowed to keep waiting at any one time during the session. If the client is not able to use HTTP Pipelining then this SHOULD be set to "1".
- ver - This attribute specifies the highest version of the BOSH protocol that the client supports. The numbering scheme is "." (where the minor number MAY be incremented higher than a single digit, so it MUST be treated as a separate integer). Note: The 'ver' attribute should not be confused with the version of any protocol being transported.
For example with curl:
$ curl --basic --user admin@ejabberd.local:changeme --data "jid=foo.bar@ejabberd.local/home&password=foo" ejabberd.local:5280/warm
<?xml version='1.0'?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"><head><title>Success</title></head><body><p>Success</p><dl class="binding"><dt class="jid">JID</dt><dd class="jid">foo.bar@ejabberd.local/home</dd><dt class="sid">SID</dt><dd class="sid">8d72a9ff0479c55338a57dce8c27d52d2934cf0d</dd><dt class="rid">RID</dt><dd class="rid">1088817781</dd></dl></body></html>
Or to try it out in the browser visit: http://ejabberd.local:5280/warm
ejabberd 2.1.0 - 2.1.x
The password of the user you wish to warm the binding for must be known. This can be handled by having a an authentication module with some type of backdoor password - or generating the ejabberd password on behalf of the user and storing it in the webservice.
Make sure that ejabberd is already installed. The build script assumes it lives at /usr/lib/ejabberd
$ git clone git://github.com/theozaurus/mod_warm_bindings.git
$ cd mod_warm_bindings
$ ./build.sh
$ sudo cp ebin/*.beam /usr/lib/ejabberd/ebin
In the ejabberd config (/etc/ejabberd/ejabberd.cfg) an admin user must be specified like:
{acl, admin, {user, "admin", "ejabberd.local"}}.
Then the ejabberd_http module must be configured correctly:
{listen,[
...
{5280, ejabberd_http, [
...
http_bind,
{request_handlers, [
{["warm"], mod_warm_bindings}
]},
...
]}
...
]}.
ejabberd can then be restarted.