8. Custom AuthRepository implementation

8.1. Credentials - solid base for authentication

Tigase supports having per-application passwords, allowing having distinct password for each application greatly improving security (see Application passwords for more details). To facilitate it uses Credentials, specified by the namesake interface: tigase.auth.credentials.Credentials, which implementations may store multiple credentials for single account (under credentialId, ie. different credentials for different authentication mechanisms).

It’s specifies a couple of essential API methods:

• boolean canLogin(); - checks if account can perform logging-in

• AccountStatus getAccountStatus(); - returns account status, i.e. if it’s enabled or not

• Entry getEntryForMechanism(String mechanism); - find a credential for specified encryption mechanism

• Entry getFirst(); - returns first available instance of credentials entry

• BareJID getUser(); - returns bare jid of an account

• boolean isAccountDisabled(); - checks if account is disabled

that allows handling of Credential entry for particular encryption/authentication mechanism. Essential part of the Credentials API are entries (defined in tigase.auth.credentials.Credentials.Entry that are actually responsible for performing provided password against defined mechanism.

8.2. Simplest AuthRepository implementation

The most basic way to create completely custom authentication is by implementing AuthRepository interface. While it has a handful or required methods the most important one is tigase.db.AuthRepository.getCredentials (it has default implementation and you could use tigase.db.AuthRepository.getPassword but it’s deprecated and will be removed).

Credentials allow having multiple, per-application passwords, but in the basic case - using PLAIN SALS method for authentication, you can use entry implementation just for plain passwords (tigase.auth.credentials.entries.PlainCredentialsEntry class) and wrap it in tigase.db.AuthRepository.SingleCredential as you would only use single password. It also requires passing parameter indicating whether the account is active (allowed to login) or disabled (not allowed to log in).

Here’s the basic snippet that will authenticate all authentication attempts if password will be used as password:

Note

Particular password retrieval method is out of scope of this document; see Using DataRepository and Accessing other repositories with DataRepository for more information on how to use Tigase API for accessing databases.

public class SimpleCustomAuthRepository implements AuthRepository {

    @Override
    public Credentials getCredentials(BareJID user, String credentialId) throws TigaseDBException {
        final String passwordFromRepository = "password";
        final PlainCredentialsEntry passwordEntry = new PlainCredentialsEntry(passwordFromRepository);
        return new SingleCredential(user, getAccountStatus(user), passwordEntry);
    }

    @Override
    public AccountStatus getAccountStatus(BareJID user) throws TigaseDBException {
        return AccountStatus.active;
    }
}

There are also 2 useful methods that are called when user is authenticated or logs out, that may optionally allow you to perform certain additional operations on repository/external services:

@Override
public void loggedIn(BareJID jid) throws TigaseDBException {

}

@Override
public void logout(BareJID user) throws TigaseDBException {

}

Complete source example is included in the sources as tigase.examples.SampleCustomAuthRepository