Chapter 15. SASL Custom Mechanisms and Configuration

Table of Contents

Basic SASL Configuration
Mechanisms Configuration
CallbackHandler Configuration
Selecting Mechanisms Available in the Stream
Built-in Mechanisms
Custom Mechanisms Development
General Remarks
Known Problems

Bartosz Malkowski <> v2.0, June 2014: Reformatted for AsciiDoc. :toc: :numbered: :website: :Date: 2013-01-23 03:54

This API is available from Tigase XMPP Server version 5.2.0 or our current master branch.

Note that API is under active development. This description may be updated at any time.

Basic SASL Configuration

SASL implementation in the Tigase XMPP Server is compatible with Java API.The same exact interfaces are used.

The SASL implementation consists of following parts:

  1. mechanism
  2. CallbackHandler

Properties list for SASL plugin (sess-man/plugins-conf/urn\:ietf\:params\:xml\:ns\:xmpp-sasl):




A factory class for SASL mechanisms. Detailed description at Mechanisms configuration


A default callback handler class. Detailed description at CallbackHandler configuration


A callback handler class for a particular mechanism. Detailed description at CallbackHandler configuration


A class for filtering SASL mechanisms available in a stream. Detailed description at Selecting mechanisms

Mechanisms Configuration

To add a new mechanism, a new factory for the mechanism has to be registered. It can be done with a new line in the file like this one:


The class must implement 'SaslServerFactory' interface. All mechanisms returned by 'getMechanismNames()' method will be registered automatically.

The factory which is available and registered by default is 'tigase.auth.TigaseSaslServerFactory' which provides PLAIN and ANONYMOUS mechanisms.

CallbackHandler Configuration

The CallbackHandler is a helper class used for loading/retrieving authentication data from data repository and providing them to a mechanism.

To register a new callback handler a new line in the file like this one has to be added:


It is also possible to register different callback handlers for different mechanisms:



During authentication process, the Tigase server always checks for a handler specific to selected mechanisms, and if there is no specific handler a default one is used.

Selecting Mechanisms Available in the Stream

Interface 'tigase.auth.MechanismSelector' is used for selecting mechanisms available in a stream. Method 'filterMechanisms()' should return a collection with mechanisms available based on:

  1. all registered SASL factories
  2. XMPP session data (from 'XMPPResourceConnection' class)

The default selector returns mechanisms from the default Tigase’s factory ('TigaseSaslServerFactory') only.

It is possible to use a custom selector by specifying it’s class int the file: