BASE Development information Plugins for user authentication

Plugins for user authentication

1. Internal vs. external authentication

BASE can authenticate users in two ways. Either it uses the internal authentiction or the external authentication. With internal authentication BASE stores logins and passwords in it's own database. With external authentication this is handled by some external application. Even with external authentication it is possible to let BASE cache the logins/passwords. This makes it possible to login to BASE if the external authentication server is down.

An external authentication server can only be used to grant or deny a user access to BASE. It can't be used to give a user permissions inside BASE.

The external authentication service is only used when a user logs in. Now, one of several things can happen:

• The login is correct and the user already exists in BASE. If the driver supports extra information and auth.synchronize is set the extra information is copied to the BASE server.
• The login is correct, but the user doesn't exists in BASE. A new user account is created. If the driver supports extra information it is copied to the BASE server (event if the auth.synchronize isn't set). The new user account will get the default quota and be added to the Users role. In the future it may be possible that this is configurable.
• The ROOT user is logging in. Internal authentication is always used for the root user.
• If password caching is enabled, the password is copied to BASE. If an expiration timeout has been set, the user will get an expiration date set.
• The authentication server says that the login is invalid or the password is incorrect. The user will not be logged in. If a user account with the specified login already exists in BASE, it will be disabled.
• The authentication driver says that something else is wrong. If password caching is enabled, internal authentication will be used. Otherwise the user will not be logged in. An already existing account is not modified or disabled.

2. The Authenticator interface

To be able to use external authentication you must have a class that implements the Authenticator interface. In your base.config file you specify the class name in the auth.driver setting and it's initialisation parameters in the auth.init setting.

Your class must have a public no-argument constructor. The BASE application will create only one instance of the class for lifetime of the BASE server. It must be thread-safe since it may be invoked by multiple threads at the same time. Here are the methods that you must implement:

public void init(String settings);

This method is called just after the object has been created with it's argument taken from the secondary.storage.driverauth.init setting in your base.config file. This method is only called once for an object. The syntax and meaning of the parameter is driver-dependent. It is irrelevant for the BASE core.

public boolean supportsExtraInformation();

This method should simply return TRUE or FALSE depending on if the authentication driver supports extra user information or not. The only required information about a user is a unique ID and the login. Extra information includes name, address, phone, email, etc.

public AuthenticationInformation authenticate(String login, String password)

Try to authenticate a login/password combination. The driver should return an AuthenticationInformation object if the authentication is successful or throw an exception if not. Exceptions:

• UnknownLoginException: This exception should be thrown if the login is not know to the external authentication system
• InvalidPasswordException: This exception should be thrown if the login is know but the password is invalid. In case it is considered a security issue to reveal that a login exists, the plugin may throw an UnknowLoginException instead.
• AuthenticationException: In case there is another problem, such as the authentication service beeing down. This exception is the only one that triggers the use of cached passwords.

3. Configuration settings

The configuration settings for the authentication driver is located in the base.config file. Here is an overview of the settings. For more information read the base.config reference

auth.driver

The class name of the authentication plugin.

auth.init

Initialisation paramters sent to the plugin by calling the init() method.

auth.synchronize

If extra user information is synchronized at login time or not. This setting is ignored if the driver doesn't support extra information.

auth.cachepasswords

If passwords should be cached by BASE or not. If the passwords are cached a user may login to BASE even if the external authentication server is down.

auth.daystocache

How many days to cache the passwords if that is enabled. A value of 0 caches the passwords for ever.