Logon Service example plus logon app download

[jasmina]

Logon Service example plus logon app download
This is an example of using simple database tables to define users and roles. A Logon Service checks the userid/password then loads any user roles. The example also includes simple pages to create and edit users and roles and save them in the database. Follow the instructions below to install and test the application.

Background info: Ebase Xi allows the authentication of users to be separately configured in a Logon Service. This provides a degree of separation between the application which the user will run and the authentication process. An application can invoke the Logon Service by calling system.securityManager.logon().

Download:
SamplePortalLogonServiceDemoApp.zip

Then run the PortalAdmin form:

Test users:
jasmina/password
frankg/password

The instructions below take you through the steps to create the application from scratch. If you've downloaded the app, you can choose to skip the rest of this document.

Step 0: Prerequisites:
Ebase Xi V5.0 or higher.
Run the SQL below to create and populate tables in the EBASE_SAMPLES database:

Code: Select all

-- SamplePortalLogonService Application - Data 

-- Table EB_LS_ROLES
DROP TABLE "EBASE_SAMPLES"."EB_LS_ROLES";

CREATE TABLE "EBASE_SAMPLES"."EB_LS_ROLES" ("ROLENAME" VARCHAR(500) NOT NULL, "DESCRIPTION" VARCHAR(500), CONSTRAINT "PK_EB_LS_ROLES" PRIMARY KEY ("ROLENAME"));
INSERT INTO "EBASE_SAMPLES"."EB_LS_ROLES" ("ROLENAME", "DESCRIPTION") VALUES ('administrator', 'Administrator, access for everything');
INSERT INTO "EBASE_SAMPLES"."EB_LS_ROLES" ("ROLENAME", "DESCRIPTION") VALUES ('services', 'Access to services');


-- Table EB_LS_USERS
DROP TABLE "EBASE_SAMPLES"."EB_LS_USERS";

CREATE TABLE "EBASE_SAMPLES"."EB_LS_USERS" ("USERNAME" VARCHAR(500) NOT NULL, "EMAIL" VARCHAR(500), "FIRSTNAME" VARCHAR(500), "LASTNAME" VARCHAR(500), "PASSWORD" VARCHAR(500), CONSTRAINT "PK_EB_LS_USERS" PRIMARY KEY ("USERNAME"));
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS" ("USERNAME", "EMAIL", "FIRSTNAME", "LASTNAME", "PASSWORD") VALUES ('jasmina', 'jasmin.ackmann@gmail.com', 'jasmin', 'ackmann', '2abeec28dd6449d746f0174b2dabad06');
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS" ("USERNAME", "EMAIL", "FIRSTNAME", "LASTNAME", "PASSWORD") VALUES ('frankg', 'frank.gehringer@gmail.com', 'frank', 'gehringer', '2abeec28dd6449d746f0174b2dabad06');
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS" ("USERNAME", "EMAIL", "FIRSTNAME", "LASTNAME", "PASSWORD") VALUES ('danielc', 'daniel.cadmen@gmail.com', 'daniel', 'cadmen', '2abeec28dd6449d746f0174b2dabad06');


--Table EB_LS_USERS_ROLES
DROP TABLE "EBASE_SAMPLES"."EB_LS_USERS_ROLES";

CREATE TABLE "EBASE_SAMPLES"."EB_LS_USERS_ROLES" ("USERNAME" VARCHAR(500), "ROLENAME" VARCHAR(500));
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS_ROLES" ("USERNAME", "ROLENAME") VALUES ('', '');
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS_ROLES" ("USERNAME", "ROLENAME") VALUES ('jasmina', 'administrator');
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS_ROLES" ("USERNAME", "ROLENAME") VALUES ('danielc', 'administrator');
INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS_ROLES" ("USERNAME", "ROLENAME") VALUES ('frankg', 'services');

--DROP TABLE "EBASE_SAMPLES"."EB_LS_USERS";
--CREATE TABLE "EBASE_SAMPLES"."EB_LS_USERS" ("USERNAME" VARCHAR(500) NOT NULL, "EMAIL" VARCHAR(500), "FIRSTNAME" VARCHAR(500), "LASTNAME" VARCHAR(500), "PASSWORD" VARCHAR(500), CONSTRAINT "PK_EB_LS_USERS" PRIMARY KEY ("USERNAME"));
--INSERT INTO "EBASE_SAMPLES"."EB_LS_USERS" ("USERNAME", "EMAIL", "FIRSTNAME", "LASTNAME", "PASSWORD") VALUES ('', '', '', '', '');
--
--SELECT "USERNAME", "EMAIL", "FIRSTNAME", "LASTNAME", "PASSWORD" FROM "EBASE_SAMPLES"."EB_LS_USERS";
--
--SELECT * FROM "EBASE_SAMPLES"."EB_LS_USERS";
--
--UPDATE "EBASE_SAMPLES"."EB_LS_USERS" SET "USERNAME" = '', "EMAIL" = '', "FIRSTNAME" = '', "LASTNAME" = '', "PASSWORD" = '' WHERE "USERNAME" = '<condition>';
--
--DELETE FROM "EBASE_SAMPLES"."EB_LS_USERS" WHERE "USERNAME" = '<condition>';

Step 1. In the designer create a project

Step 2. Create a new Logon Service in your project
Right click on the project and enter New > System Service > Logon Service
Tip: Take a note of the web service name, it will be used in API calls later!

Step 3. Create Database Resources User and UserRoles and map them to the Logon Service fields WORK_PASSWORD, WORK_USERID (User resource) and table USER_ROLES (UserRoles resource)

Code: Select all

Database Resource [b]User[/b]: 
SELECT "PASSWORD" FROM "EBASE_SAMPLES"."EB_LS_USERS WHERE USERNAME=&&USERNAME;

Database Resource [b]UsersRoles[/b]:
SELECT "ROLENAME" FROM "EBASE_SAMPLES"."EB_LS_USERS_ROLES" WHERE USERNAME=&&USERNAME;

Step 4. Create a script to run in the Logon Service
Create a new script and paste the code below, then add the script to the Logon Service's Integration event

Code: Select all

importPackage(com.ebasetech.xi.api);
importPackage(com.ebasetech.xi.services);

/** 
 *  At this entry point the fields PARAM1_VALUE and PARAM2_VALUE is prepopulated through an api call
 *  PARAM1_VALUE mapped to an incoming parameter userName value 
 *  PARAM2_VALUE mapped to an incoming parameter password value
 *  
 *  And we will check the userid/password combination against ebase_sample database and 
 *  populate Fields USERID and Table CUSTOMROLE with a user role
 *  
 *  Table CREDENTIAL- is not populate in this sample but we could have done it if we wanted with additional 
 *  user credentials id/value e.g email/jasmina@gmail.com.
 *  
 *  Table EBASEROLE - populating ignored, we are not using workflow module 
 */

/**
 * checks userid/password combinations against ebase_sample database
 */

/**
 * 
 * @type {string}
 */
var userid = fields.PARAM1_VALUE.value.trim();  
var pwd = fields.PARAM2_VALUE.value.trim();  


/** @type {string} */
fields.USERID.value = null;

/**
 * Checks user credential and populates the logon service tables
 * @param {string} userid
 * @param {string} pwd
 */

if(authenticateUser(userid,pwd)){
	
	readUserRoles(userid);
	fields.USERID.value = userid; //set the authenticated user id
	
}else {
	fields.ERRORCODE.value = "Authentication failed: ";
	fields.ERRORDESCRIPTION.value = "Unauthorized user. Check username and password and try again.";

	}

/**
 * Checking userid/password combinations against a database
 *
 * @param {string} userid
 * @param {string} pwd
 * @return {boolean} 
 */
function authenticateUser(userid,pwd){
		
	fields.WORK_USERID.value = userid;
	resources.User.fetch();
	
	//var mypassword = EncryptionServices.encrypt("password");
	
	var password = EncryptionServices.decrypt(fields.WORK_PASSWORD.value);

	//check if login pwd matches the password from the database 
	if( password == pwd){
		return true;
	}

	return false;

}

/**
 * 
 * Takes an userid and populates USER_ROLES and CUSTOMROLE Table 
 * *
 * @param {string} userid
 */
function readUserRoles(userid){
	tables.USERS_ROLES.USERNAME.value = userid;
  var roles = tables.USERS_ROLES.fetchTable();
  
  tables.CUSTOMROLE.copyTable(tables.USERS_ROLES, false);
 	tables.CUSTOMROLE.updateTable();
}

// When we are here logon service has established the users credentials
// Meaning that CUSTOMROLE table is populated with user role
// Meaning that USERID is populated

// We can make api call from a before form event script:
// system.securityManager.isUserLoggedOn();
// system.securityManager.hasRole(String userRole);

// and from a submit button click event script then we can establish a logon service call
// system.securityManager.logon(String webServiceName,Array inParameters);

Step 5. Test the Logon Service by opening it in the designer and clicking the run icon on the tool bar
Enter test request parameters as follows then click "Submit":
PARAM1_VALUE:user
PARAM2_VALUE:password

Code: Select all

<xml>
<req>
<req>jasmina</req>
<req>string</req>
<req>password</req>
<req>string</req>
<req>string</req>
<req>string</req>
</req>

Step 6. Check Logon Service response body. It should return the user credentials:

Code: Select all

<res&#58;Response xmlns&#58;soap="http&#58;//schemas.xmlsoap.org/soap/envelope/" xmlns&#58;res="http&#58;//www.ebasetech.com/logon/Response"&#58;
<res&#58;USERID&#58;jasmina</res&#58;USERID&#58;
<res&#58;CUSTOMROLES&#58;
<res&#58;CUSTOMROLE&#58;
<res&#58;ROLEID&#58;administrator</res&#58;ROLEID&#58;
</res&#58;CUSTOMROLE&#58;
</res&#58;CUSTOMROLES&#58;
</res&#58;Response&#58;

The Logon Service validated that the user "jasmina" with an administrator role exists.
What we've accomplished so far: The Logon Service has been created and tested successfully and from now on it can be called programmatically from a form script.

Step 7. Every form created in your project which requires authentication needs to add a before form event script to verify that a user has signed on. If the user has not yet signed on, they will be redirected to a login page

Code: Select all

	
/**
 * Verify the user's credentials via server side service lookup.
 * No credentials user is sent to a login page
 * IMPORTANT: used only if the CUSTOMROLE TABLE and USERID field in logon service is populated at runtime
 */
if (!system.securityManager.isUserLoggedOn()) {
	
		//Navigate to portal login
		form.gotoForm("PortalLogin");  
}

Step 8. Create a user login form
The script below passes the userid and password to the Logon Service for validation using system.securityManager.logon(). If the call was successful - credentials for the user is established.

Code: Select all

/**
 * Validating user credentials via logon service 
 * API: system.securityManager.logon(String webServiceName,Array inParameters); 
 * TIP: webServiceName, Located in logon service entity e.g. samplePortalLogonWebService
 */
try {
   // Form fields
    var userName = fields.USER.value;
    var password = fields.PASSWORD.value;

    //validating user credentials via logonService
    //initialize the samplePortalLogonWebService fields 

    //[PARAM1_SOURCE : PortalLoginForm_Param1_UserName,PARAM1_VALUE : userName]
    //[PARAM2_SOURCE : PortalLoginForm_Param2_Password,PARAM2_VALUE : userName]

    system.securityManager.logon("samplePortalLogonWebService", [
        ["PortalLoginForm_Param1_UserName", userName],
        ["PortalLoginForm_Param2_Password", password]
    ]);

    //event.owner.addWarningMessage("Validated user credentials for: "+ system.securityManager.userName + " " + system.securityManager.userLoggedOn);

} catch (err) {
    event.owner.addErrorMessage("LogonException: " + err);

}

//At this point we have a validated user and associated roles

if (system.securityManager.hasRole("administrator")) {
   form.gotoForm("PortalAdmin");

}