Chapter 15. SASL Custom Mechanisms and Configuration

Table of Contents

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

Bartosz Malkowski <bmalkowski@tigase.pl> v2.0, June 2014: Reformatted for AsciiDoc. :toc: :numbered: :website: http://tigase.net/ :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):

Property

Description

factory

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

callbackhandler

A default callback handler class. Detailed description at CallbackHandler configuration

callbackhandler-${MECHANISM}

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

mechanism-selector

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 init.properties file like this one:

sess-man/plugins-conf/urn\:ietf\:params\:xml\:ns\:xmpp-sasl/factory=com.example.OwnFactory

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 init.properties file like this one has to be added:

sess-man/plugins-conf/urn\:ietf\:params\:xml\:ns\:xmpp-sasl/callbackhandler=com.example.DefaultCallbackHandler

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

sess-man/plugins-conf/urn\:ietf\:params\:xml\:ns\:xmpp-sasl/callbackhandler-PLAIN=com.example.PlainCallbackHandler

sess-man/plugins-conf/urn\:ietf\:params\:xml\:ns\:xmpp-sasl/callbackhandler-OAUTH=com.example.OAuthCallbackHandler

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 init.properties file:

sess-man/plugins-conf/urn\:ietf\:params\:xml\:ns\:xmpp-sasl/mechanism-selector=com.example.OwnSelector