The Liberator Auth API enables developers to create Liberator Auth Modules for the Caplin Liberator. This document refers to the Java API, a C API is also available. Caplin Liberator supports a modular system for handling authentication of users and entitlement of objects. This allows users to be authenticated for login, object-level read and write permissions for a user to be checked and object name mappings to be performed. Session management is also possible - actions such as ejection and re-validation of Liberator sessions are supported.
- Authentication is the process of determining whether someone is who they say they are. In networks such as the Internet, authentication is commonly done through the use of logon tokens. These can take the form of plaintext passwords or more complex encrypted tokens. Knowledge of the token is assumed to guarantee that the user is authentic.
- Authorisation / Entitlement is the process of giving and checking someones permission to do or have access to something. A system administrator defines which users are allowed access to which objects; the actual checking of the permission values that have been set up are performed by the Liberator Auth API.
Included with the Liberator are a number of standard Auth Modules:
- openauth will allow any username to enter the system and with any password. It can also specify whether all users have either or both read and write access to any object in the system.
- cfgauth allows the number of users and the types of objects they can read to be configured.
- XMLauth enables programmers and system administrators to use XML to create their own permissioning structures and control entitlement to objects held on Caplin Liberator.
Please see the Liberator Administrator's Guide and XML Auth Module User Guide for more information on these modules.
The diagrams below give a step by step illustration of how Liberator Auth Modules are used to perform permissioning and entitlement.
Creating an Liberator Auth Module
A Liberator Auth Module is created by implementing the
Authenticator interface. There is a default implementation adaptor (
AuthenticatorAdaptor that can be extended if only a few custom methods are needed.
The API is callback-based. Calls are made on the various Authenticator methods as and when an Auth action occurs in the Liberator. All the callback methods need to return an
AuthenticationResult instance to represent the result of the Auth call.
The table below lists the object types to use in order to create a Liberator Auth Module.
|Represents a client connection session to Caplin Liberator and also holds an
||Represents a user and their login token.|
||Represents an RTTP data object, for example a record, page, directory or news item. Callbacks are made when objects are created / deleted in the Liberator and also for user entitlements.|
||Represents an object mapping. The Liberator Auth API provides a mechanism for mapping a requested object name to a different name in the Liberator. See
||Represents information about the Liberator node. Information available from the server is an identifier string and current / max session counts.|
|Delayed Result Receiver||
||Used, if required, for notifying delayed authentication results of User Authentication checks and Object mappings.|
||Provides the ability to force the Liberator to eject or re-validate individual sessions or groups of sessions.|
The Liberator Auth Module is automatically constructed by the Liberator, so you must provide a default constructor. This should not perform initialisation or startup actions. Instead, the
Authenticator.initialise method, which is called by the Liberator on initialisation, should be used for this purpose.
The Authenticator.initialise method provides
ServerNode instances that can be used to perform their respective operations. A String reference to a standard Java Logger is also passed-in. This logger gives access to the Liberator's auth log file and should be used for application logging. See
OpenAuthenticator for a sample implementation.
One of the static instances of
AuthenticationResult should be returned to indicate the restult of an Authentication or Entitlements call. Some return codes only apply to certain subsets of the methods.
||Authentication is successful|
||The username provided is invalid|
||The password / token provided is invalid|
||The machine address provided is invalid|
||The user's account has expired|
||The user's total number of permitted licences has been exceeded|
||The site's total number of permitted licences has been exceeded|
||An error occurred during authentication|
||Authentication is delayed|
||No Mapping occured (Only used for mapObject calls)|
As well as the standard return codes, some methods can return a range of codes which have no specified meaning. This allows an Liberator Auth Module and a custom client application to provide custom messages for denying access. These codes are
These codes will result in a "Read Denied" action on the RTTP client side, but with a different code. If you are using one of the standard RTTP clients (such as WebSheet or StreamLink for Excel) then these codes result in a standard "Read Denied" message, but when using a custom-built client it is possible to handle the different codes in a way that suits your application needs.
The codes will be the standard "Read Denied" code plus the user-defined code used (e.g. 1 for
Custom clients can be built using the StreamLink APIs.
Authenticator.checkUpdate(com.caplin.server.auth.UserSession, com.caplin.server.auth.RTTPObject, java.lang.String) method enables you to check permissioning for each individual update. Note: This currently only works for news headlines, and only if the sending DataSource specifies per-update authorisation. No code is returned from this call.
Content-based permissioning works by allowing users to see an object only if the object contains a certain value in one of its fields, as opposed to subject-based permissioning, which allows users to see an object based on the symbol name.
RTTPObject.getValue method can be used to access the current field value of an object. The authentication result can then be determined using this value.
SessionManager provides methods to eject and invalidate users, typically called when the licence count has reached the maximum, or from an administration front end of your Liberator Auth Module. These methods are used for the following purposes:
- kick out a logged-in user when a new user logs in with the same details
- kick out a logged-in user when a new user logs in with the same details from a specified application
- kick out a logged-in user when new user with the same details logs on to a different machine to the one specified.
You can also invalidates a session using the
SessionManager.invalidateAllSessions methods. Invalidating a user session results in the Liberator re-checking all read permissions for the user. It can also re map any objects. This is controlled by the
InvalidationType parameter. This enables the Liberator Auth Module to adjust a user's permissions / mappings in the middle of a session.
Calls to the Liberator Auth Module must not block or there will be delays to some or all of the Liberator system.
For this reason it is possible to return
DELAYED and starting another thread to do the work for you. Returning
DELAYED means that there is no blocking while a database is accessed or any other other blocking call is made.
You can also return
DELAYED after mapping an object name.
Following a return of this value, the
DelayedResultReceiver should be used to return the actual auth result, when available.
The Caplin KeyMaster generates single-use encrypted tokens that are used as the client login password to the Liberator. The KeyMaster uses a private key to encrypt the token and the Liberator holds the corresponding public key that is used for decryption. This ensures that only the KeyMaster could possibly generate a valid token that is used for login. When the KeyMaster server is protected behind a single-signon system this allows the Liberator to use the same single signon mechanism without the need for direct connection to the signon database or back-end system.
The Liberator Auth API provides a mechanism for validating these tokens by using the
SessionManager.checkSignature(String keyIdentifier, String token) method. If a user is know to be presenting a KeyMaster token as a password during login, then a call to this method will cause the Liberator to check the validity of the token. This return value can then be used as the return to the
Permission Objects are used to change permission settings in the Liberator Auth Module. The updated permission data is sent to the Liberator in a DataSource message and the
Authenticator.checkPermissionUpdate method is called once for each user who is subscribed to the Permission Object. The Permission Object can also be forwarded on to the client interface to facilitate UI changes for the new permissions (eg for removal or addition of display elements). The structure of a Permission Object is similar to a Type 2 Record.
Global Permission Objects are used to send control data to the Liberator Auth Module. The updated data is received by the
Authenticator.globalPermissionUpdate method and can be used for any Liberator Auth Module task. Data is sent to the Liberator in the same structure as a regular Permission Object but is not applied to a particular user and is not forwarded on to the client interface.