Liberator Auth API 8.0.3-315031-546c6d47
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
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. |
Initialisation
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.