Chapter 15. SASL Custom Mechanisms and Configuration
Prev |  | Next

# Chapter 15. SASL Custom Mechanisms and Configuration

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`

Prev |  | Next
Chapter 14. Plugin Development | Home | Logging/Authentication