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 remainder of this document details the development of a custom Liberator Auth Module using the Liberator Auth API. Follow the links on the table below for information on the following topics:

How Liberator Auth Modules work
Objects used by Liberator Auth Modules
Authorisation / Entitlement return values
Content-based permissioning
Ejecting and invalidating sessions
Blocking and events
Caplin KeyMaster integration
Permission Objects
Global Permission Objects

How Liberator Auth Modules work

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.


Objects used by Liberator Auth Modules

The table below lists the object types to use in order to create a Liberator Auth Module.

Name Object Description

RTTP Session


Represents a client connection session to Caplin Liberator and also holds an AuthenticationUser. This object is available and used for both authentication and entitlement.
User AuthenticationUser Represents a user and their login token.
RTTP Object RTTPObject 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.
Map Object MapObject 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 Authenticator.mapObject for more details on this feature.
Server Node ServerNode Represents information about the Liberator node. Information available from the server is an identifier string and current / max session counts.
Delayed Result Receiver DelayedResultReceiver Used, if required, for notifying delayed authentication results of User Authentication checks and Object mappings.
Session Manager SessionManager 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 SessionManager, DelayedResultReceiver, and 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.


Return codes from Authentication or Entitlements methods

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.

Code Meaning
OK Authentication is successful
INVALID_USER The username provided is invalid
INVALID_PASS The password / token provided is invalid
INVALID_ADDR The machine address provided is invalid
ACCT_EXPIRED The user's account has expired
USER_LC_EXCEEDED The user's total number of permitted licences has been exceeded
SITE_LC_EXCEEDED The site's total number of permitted licences has been exceeded
ERROR An error occurred during authentication
DELAYED Authentication is delayed
FALSE No Mapping occured (Only used for mapObject calls)

User-defined authorisation codes

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 USER1 to USER5 inclusive.

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 USER1).
Custom clients can be built using the StreamLink APIs.


Checking updates

The 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

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.

The 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.


Ejecting and invalidating sessions

The 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.invalidateSessions or 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.


Blocking and events

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.


Caplin KeyMaster integration

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 Authenticator.checkUser(com.caplin.server.auth.UserSession) call.


Permission Objects

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

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.


Package Description