Session Management

Shared Sessions

It’s possible to enable shared sessions whereby users already logged in to your website will also automatically be logged in on the XMPP server.

Once a user is logged in, the session will be kept alive across page loads.

There are several ways to let your users be automatically authenticated to an XMPP server once they’ve logged in to your site.

Option 1: Server-side authentication via BOSH prebinding

Prebinding refers to a technique whereby your web application sets up an authenticated BOSH session with the XMPP server or a standalone BOSH connection manager.

Once authenticated, it receives RID and SID tokens which need to be passed on to Converse. Converse will then attach to that same session using those tokens.

It’s called “prebind” because you bind to the BOSH session beforehand, and then later in the page you just attach to that session again.

The RID and SID tokens can be passed in manually when calling converse.initialize, but a more convenient way is to pass Converse a prebind_url which it will call when it needs the tokens. This way it will be able to automatically reconnect whenever the connection drops, by simply calling that URL again to fetch new tokens.

Prebinding reduces network traffic and also speeds up the startup time for Converse. Additionally, because prebind works with tokens, it’s not necessary for the XMPP client to know or store users’ passwords.

One potential drawback of using prebind is that in order to establish the authenticated BOSH session server-side, you’ll need to access and pass on the XMPP credentials server-side, which, unless you’re using tokens, means that you’ll need to store XMPP passwords in cleartext.

This is however not the case if you for example use LDAP or Active Directory as your authentication backend, since you could then configure your XMPP server to use that as well.

To prebind you will require:

• A BOSH-enabled XMPP server for Converse to connect to (see the bosh_service_url under Configuration)
• A BOSH client in your web application (written for example in Python, Ruby or PHP) that will set up an authenticated BOSH session, which Converse can then attach to

Note

A BOSH server acts as a bridge between HTTP, the protocol of the web, and XMPP, the instant messaging protocol.

Converse can only communicate via HTTP (or websocket, in which case BOSH can’t be used). It cannot open TCP sockets to communicate to an XMPP server directly.

So the BOSH server acts as a middle man, translating our HTTP requests into XMPP stanzas and vice versa.

Jack Moffitt has a great blogpost about this and even provides an example Django application to demonstrate it.

When you authenticate to the XMPP server on your backend application (for example via a BOSH client in Django), you’ll receive two tokens:

• Session ID (SID): A unique identifier for the current session. This number stays constant for the entire session.
• Request ID (RID): A unique identifier for the current request (i.e. page load). Each page load is a new request which requires a new unique RID. The best way to achieve this is to simply increment the RID with each page load.

You’ll need to configure Converse with the prebind_url setting.

Please read the documentation on that setting for a fuller picture of what needs to be done.

Example code for server-side prebinding

• PHP: See xmpp-prebind-php by Michael Weibel and the folks from Candy chat.
• Python: See the example Django application by Jack Moffitt.

Option 2: Delegated authentication (external authentication)

Delegated authentication refers to the use case where the XMPP server delegates authentication to some other service.

This could be to LDAP or Active Directory, or it could be to an OAuth provider, a SQL server or a specific website.

The Prosody webserver has various user-contributed modules which delegate authentication to external services. They are listed in the Prosody community modules page. Other XMPP servers have similar plugin modules.

If your web-application has access to the same credentials, it can send those credentials to Converse so that users are automatically logged in when the page loads.

This can be done by setting auto_login to true and configuring the credentials_url setting.

Option 3: Temporary authentication tokens

The first option has the drawback that your web-application needs to know the XMPP credentials of your users and that they need to be stored in the clear.

The second option has that same drawback and it also needs to pass those credentials to Converse.

To avoid these drawbacks, you can instead let your backend web application generate temporary authentication tokens which are then sent to the XMPP server which in turn delegates authentication to an external authentication provider (generally the same web-app that generated the tokens).

This can be combined with prebind or with the credentials_url setting.

Option 4: Cryptographically signed tokens

Another potential option is to generate cryptographically signed tokens (e.g. HMAC tokens) which the XMPP server could authenticate by checking that they’re signed with the right key and that they conform to some kind of pre-arranged format.

In this case, you would also use the credentials_url setting, to specify a URL from which Converse should fetch the username and token.

Keeping users logged-in across page reloads

If you’ve properly set up shared session support, then your users will stay logged-in to the XMPP server upon page reloads.

However, if users are logging in manually, then users might get logged out between requests.

Credential Management API

Users with modern browsers which properly support the Credential Management API should be automatically logged-in across page reloads and therefore maintain their sessions.

Using a cookie

The main reason why users can get logged-out between page reloads is because we don’t (and can’t) use cookies to maintain user sessions as is usually done with websites.

This is because XMPP servers generally don’t have support for logging in with a cookie. It would be theoretically possible to login with SASL-EXTERNAL and a cookie which the XMPP server looks up as part of the BOSH HTTP request or the websocket connection, but no XMPP servers currently support this out of the box.

Prosody does have a plugin called mod_auth_http_cookie which does the above. You’d have to configure Converse to use SASL-EXTERNAL and then set up Prosody with that plugin. (Note, this setup has not yet been tested personally).

This is however not a cross-platform solution and won’t work for hosters who want to support all or multiple XMPP servers.

Storing the password in localStorage

Since cookies are usually not an option, people have suggested storing the password in localStorage and logging in with it again when the user reloads the page.

We’ve purposefully not put this functionality in Converse due to the security implications of storing plaintext passwords in localStorage.

Storing the SASL SCRAM-SHA1 hash in IndexedDB

Another approach is to store the SCRAM-SHA1 computed clientKey in localStorage and to use that upon page reload to log the user in again.

This has been implemented since version 10, see documentation on reuse_scram_keys.