Logon Service
See also: Xi Logon Exit, Roles and Credentials
Description
A Logon Service is a System Service (a special type of Integration Service) which is used to authenticate users. A Logon Service is responsible for checking that a user is valid (e.g. by checking a userid/password) and then setting the userid for the rest of the user’s session. Optionally, additional information - roles and credentials – can be associated with the user, and these can be used subsequently for security checks or to perform workflow assignments.
A Logon Service can be used for any or all of the following:
· Checking userid/password combinations against a database
· Looking up a userid in an LDAP Registry (such as Active Directory)
· Obtaining user roles
· Obtaining user credentials such as email, department, manager etc
Information about the user is supplied by the caller and is passed into the Logon Service in a Request document. This might contain a userid/password combination entered by the user, or a userid extracted from the application server (e.g. for Windows domain single sign-on), or some sort of user token extracted from the Http request (this approach is typically used by single sign-on systems), or any combination of these.
A Logon Service can be invoked automatically when a new session connects using the Xi Logon Exit or it can be invoked programmatically at any time e.g. when a user attempts to access a restricted service. This is an important distinction: when the Logon Service is invoked for all new sessions, then only authenticated users will have access to the system; when the Logon Service is invoked programmatically you can control the point(s) at which authentication is required, and this makes it possible to mix authenticated and unauthenticated users in the same system.
Any number of Logon Services can be created and the specific service to be used can be specified when the Logon Service is called programmatically. However, when the Logon Service is called when a new session connects, only one Logon Service can be used and this service is configured as the default Logon Service using Server Administration Security Properties property Default Logon Service Web Service Name.
Each Logon Service is uniquely identified by a unique Web Service Name which is configured using the Logon Service Editor, and this name is used to call the service by all clients.
Each Logon Service is linked to a Logon Service Resource which defines the format of the Request and Response documents used by the service (these are described in detail below). The format of these documents is fixed and can’t be changed and therefore a Logon Service Resource is read only – it can’t be saved. When you create a new Logon Service, a new Logon Service Resource is also created at the same time and all the fields and tables from the resource have been imported into the service and mapped. All you need to do to use this service is add a script and any additional fields and tables required by the script.
A Logon Service is supplied with the system: LOGON_SERVICE in project System Services and has a web service name of ebaseLogonService. See Supplied Implementation for details.
How it works
When a service is invoked, the script configured for the Logon Service’s integration event is executed. This script processes the information passed in the Request document, performs whatever processing is required, then builds a Response document that contains an authenticated userid, and optionally role and credential information for the user.
The format of the input and output documents for the service is defined in the Logon Service Resource linked to the service and cannot be changed. The input format is defined by the Request document and consists of up to three parameters where each parameter has a value and source type. This Request document represents the user’s security credentials e.g. userid + password or some sort of token. When the logon service is called from the Xi Logon Exit each time a new session connects, these security credentials are extracted from the HTTP request – how this is done is configured by the Xi Logon Exit. When the logon service is called from a script, the security credentials are supplied by the script – typically these are userid and password.
The format of the output is defined by the Response document, and must be populated by the script:
USERID: this must be set by the implementing script – failure to do this will result in a failure. This userid is then accepted by the system as authenticated and is used for the duration of the user’s session.
CUSTOMROLES: this is an optional table of custom roles that will be added to the user’s security definition.
EBASEROLES: this is an optional table of Ebase roles that will be added to the user’s security definition. Note that when using Ebase Workflow with the strict security handler configured, at least one Ebase role should be configured to provide the user with security authorizations required by the workflow system.
CREDENTIALS: this is an optional table of credentials that will be added to the user’s security definition.
ERRORCODE: set this to a value other than 00000 to indicate that the logon has failed.
ERRORDESCRIPTION: set this in conjunction with ERRORCODE to indicate the reason why the logon has been rejected.
Testing
A Logon Service can be tested by clicking the test icon 
on the editor toolbar. The test dialog shown
below is then displayed. Fill in test values in the request document and click
the Submit button.
Supplied Implementation
A Logon Service is supplied with the system: DefaultLogonService at path System_Services/DefaultLogonService in project ebaseSamples and has a web service name of ebaseLogonService. Authentication is performed by one of the following 2 scripts, depending on version of Ebase Xi:
1. JS_LOGON_SERVICE_LOGIC javascript script – is used starting from Ebase Xi V4.5.2. This script calls functions defined in script JS_LOGON_SERVICE_FUNCTIONS (these functions are not shown below).
This script supports users connected to a Windows domain who have already authenticated against Active Directory. If no Windows domain user is passed in, a signon JSP panel is displayed requesting userid and password and these are authenticated using the internal Ebase Security System. The service is called from the Xi Logon Exit for all new sessions and the input parameters for the Request document are configured via XI Logon Exit User Source Parameters in the Server Administration Application with the following values.
Logonexit.ParameterName1=remoteUser
Logonexit.ParameterSource1=HEADER
This supplies the Windows domain userid as the first input parameter in the Request document.
importPackage(com.ebasetech.xi.api);
importPackage(com.ebasetech.xi.services);
var useridSource =
fields.PARAM1_SOURCE.value;
var userid =
fields.PARAM1_VALUE.value;
var pwd =
fields.PARAM2_VALUE.value;
fields.USERID.value = null;
// 1.
Check for no userid provided, send user to JSP signon panel
if ( !userid )
{
fail("JSP",
"Blank userid: PARAM1_VALUE is null");
}
// 2.
Check for userid provided by application server,
probably via integration with Active Directory.
// Accept the user id and setup security roles - one role for
each AD group.
//
Extract any user attributes from AD and add these as credentials.
// Also include the internal workflow role to allow ALL
workflow operations by this user
else if ( isUseridFromApplicationServer(useridSource, userid) )
{
populateRolesFromADGroups(userid);
populateAttributesFromAD(userid);
populateRolesForWorkFlow();
}
// 3.
Check for input is from JSP signon panel
else if ( isJSPSignon(useridSource)
)
{
// authenticate userid
against Ebase internal security system and populate internal security roles
if ( authenticateInternalUser(userid, pwd) )
{
getInternalRoles(userid);
}
else
{
// if authentication fails, set error code
to 'JSP' to indicate try again (up to configured maximum attempts)
fail("JSP",
"Invalid userid/password combination...");
}
}
// If
we reach this point, we have a valid user, so set this in the response document
to indicate successful signon
fields.USERID.value = userid;
// Uncomment this while testing - it Writes contents of
EBASEROLES, CUSTOMROLES and CREDENTIALS tables to the application server log
// printRolesAndCredentials(userid);
2. LOGON_SERVICE_LOGIC FPL script. Is used in Ebase V4.5.1 and earlier. This authenticates a supplied user/password combination against the internal Ebase Security System and adds any defined roles.
if [PARAM1_SOURCE = 'JSP']
// authenticate userid
(PARAM1_VALUE) and password (PARAM2_VALUE) against Ebase internal security
system
if [ javamethod('com.ebasetech.ufs.security.authentication.EbaseUserManager.authenticateEbaseUser',
PARAM1_VALUE, PARAM2_VALUE) ]
// authentication successful, so..
// 1. set the
user id in the response
set USERID =
PARAM1_VALUE;
// 2. fetch the
Ebase security roles from the database and transfer them to the response
set
EBASE_INTERNAL_ROLES-USERID = USERID;
fetchtable EBASE_INTERNAL_ROLES;
copytable EBASE_INTERNAL_ROLES to
EBASEROLES;
updatetable EBASEROLES;
else
// authentication failed: return with error
set ERRORCODE =
'1';
set ERRORDESCRIPTION = 'Invalid userid/password
combination';
endif
endif
Invoking the Logon Service
The Logon Service can be invoked in two ways:
1. Automatically – when a user first connects, using XILogonExit
2. On demand – using SecurityManager.logon()
Users can be authenticated at any time by calling the SecurityManager.logon() method – this is only available to API scripting languages such as Javascript. Use of this method makes it possible to mix authenticated and unauthenticated users in the same system, authenticating users at the point where they need to access a protected service.
The following example shows a logon function where form fields USER and PASSWORD contain the userid and password, and the parameter source type for both is arbitrarily set to “Script” (which might be checked by the Logon Service). The function returns true if the logon is successful, and generates and error message and returns false if it fails. When the Logon Service returns an error code or fails to set a userid in the response document, a LogonException is thrown and this exception contains the error code and error description returned by the Logon Service.
function logon()
{
try
{
system.securityManager.logon([
["Script", fields.USER.value],
["Script", fields.PASSWORD.value] ] );
return
true;
}
catch
(e)
{
event.owner.addErrorMessage(e.javaException.message, false);
event.owner.addErrorMessage("code:
" + e.javaException.errorCode + ",
description: " + e.javaException.errorDescription);
return
false;
}
}
The logon() method can also optionally accept the web service name of the service to be called as the first parameter e.g.
system.securityManager.logon("activeDirectoryService",
[ ["Script", fields.USER.value],
["Script", fields.PASSWORD.value] ] );