Introduction

This article describes how to setup a hybrid IBM Worklight application that automatically logs a user in on startup to a server that has been setup with single sign-on (SSO), and has an IBM WebSphere Portal server on the same host. Having the servers set up with SSO enables users to simply log in once to the Worklight server, and then be automatically authenticated to your other servers on the same host.

Many mobile applications also offer the ability to store user credentials such that you can simply open the application and see this information. To add this into the sample application, you can implement the encrypted cache from Worklight to store the user login information for future login attempts. This enables users to open the application and be logged into their accounts across both Worklight and WebSphere Portal servers.

Prerequisites

This article uses WebSphere Portal V8, and Worklight V5.0.0.3. While WebSphere Portal is used here, any server that supports SSO through an LDAP user registry and LTPA token authentication should be compatible with correct configuration of those settings.

Before continuing with this exercise, be sure that you have:

• An LDAP server installed and running.
• WebSphere Portal V8 server installed and running.
• IBM Worklight Server installed using the default Liberty profile and Derby database.

Because you will be setting up SSO between a Liberty profile server running Worklight and a WebSphere Portal server, both servers need to be configured to use the same user registry, share LTPA keys, and be set to use a specified domain for SSO to work.

Back to top

Setup Liberty profile server

After installing Worklight Server with the default Liberty profile and Derby database, the server needs to be configured to use the LDAP server. The Liberty profile handles configuration through a set of defaults it uses unless you specify otherwise within the server.xml file. Depending on whether you are using Linux® or Windows®, this file is located at:

• Linux: <WorklightInstallDirectory>/server/wlp/usr/servers/worklightServer/server.xml
• Windows: <WorklightInstallDirectory>\WAS85liberty-server\server\wlp\usr\servers\worklightServer\server.xml

Make these changes inside the server.xml file:

1. Change the name of the JSESSION cookie so that it doesn't conflict with the WebSphere Portal server. To do this, add the httpSession XML tag after the closing httpEndpoint tag with the cookie name attribute set as shown in Listing 1.
   
   Listing 1. JSESSIONID name change
   

   <httpEndpoint host="*" httpPort="9080" httpsPort="9443" id="defaultHttpEndpoint"> <!-- Begin of options added by IBM Worklight installer. --> <tcpOptions soReuseAddr="true"/> <!-- End of options added by IBM Worklight installer. --> </httpEndpoint> <httpSession cookieName="JSESSIONID_wl"/>

   
   
2. Remove the default user registry installed. The server will have errors with multiple user registries active. Locate the basicRegistry segment, shown in Listing 2, and remove it.
   
   Listing 2. Basic registry entry
   

   <!-- Declare the user registry for the IBM Application Center. --> <basicRegistry id="applicationcenter-registry" realm="ApplicationCenter"> <!-- The user "appcenteradmin" has special privileges within the IBM Application Center. --> <user name="appcenteradmin" password="admin"/> <!-- The other users have normal privileges. --> <user name="demo" password="demo"/> <group name="appcentergroup"> <member name="appcenteradmin"/> <member name="demo"/> </group> </basicRegistry>

   
   
3. Next, you will add the LDAP user registry. Listing 3 shows an example of the configuration used; however, the information in bold will need to change depending on how you setup your LDAP. The Liberty profile also has additional filters, such as the userFilter only for other aspects of the LDAP server, such as groups. Additionally, if your LDAP server is setup to use SSL there are options you can use to configure that as well. See the Information Center for more information on server.xml configuration options or connecting to an LDAP server that is using SSL.
   
   Listing 3. LDAP configuration XML
   

   <ldapRegistry id=”ldap” realm=”defaultWIMFileBasedRealm” host=”<ldap host>” port=”389” ignoreCase=”true” baseDN=”dc=ibm,dc=com” bindDN=”cn=root” userFilter=”(&(uid=%v)(objectclass=inetOrgPerson))” bindPassword=”<password>” ldapType=”IBM Tivoli Directory Server”> </ldapRegistry>

   
   
4. Change the server security to use SSO cookies being set to the proper domain, which can be set directly after the ldapRegistry entry. Substitute the bold domain name below for the domain you will be working on:

   <webAppSecurity singleSignonEnabled=”true” ssoDomainNames=”.some.domain.com”/>

5. To double check the configuration and generate an LDAP key, start up the server. Navigate to <WorklightInstallDirectory>/server/wlp/bin and then run this command to start the server:
   • Linux: sudo ./server start worklightServer
   • Windows: server.bat start worklightServer
   Check the log file to make sure the server started up successfully with your configurations:
   • Linux: <WorklightInstallDirectory>/server/wlp/usr/servers/worklightServer/logs/console.log
   • Windows: <WorklightInstallDirectory>\WAS85liberty-server\server\wlp\usr\servers\worklightServer\logs\console.log
6. Stop the server:
   • Linux: sudo ./server stop worklightServer
   • Windows: server.bat stop worklightServer

Back to top

Setup WebSphere Portal server

1. To setup the WebSphere Portal server's LDAP, you will create an ldapConfig.properties file with some of the configuration information shown in Listing 4, based on your LDAP values. You will need to replace the values for most of these properties based on the configuration of your server. The values should match what you used for much of the configuration of the Liberty profile server's LDAP.
   
   Listing 4. Portal LDAP properties
   

   WasPassword=<WAS PW> PortalAdminPwd=<Portal PW> federated.ldap.id=myLDAP federated.ldap.host=<host> federated.ldap.ldapServerType=IDS federated.ldap.port=389 federated.ldap.baseDN=dc=ibm,dc=com federated.ldap.bindDN=cn=root federated.ldap.bindPassword=<LDAP bind PW> federated.ldap.et.personaccount.objectClasses=inetOrgPerson federated.ldap.et.personaccount.objectClassesForCreate=inetOrgPerson federated.ldap.et.personaccount.searchFilter= federated.ldap.et.group.objectClasses=groupOfUniqueNames federated.ldap.et.group.objectClassesForCreate=groupOfUniqueNames federated.ldap.et.group.searchFilter= federated.ldap.gm.dummyMember=uid=dummy federated.ldap.gm.groupMemberName=uniqueMember federated.ldap.gm.objectClass=groupOfUniqueNames federated.ldap.gm.scope=nested federated.ldap.loginProperties=uid;mail personAccountParent=cn=users,dc=ibm,dc=com groupParent=cn=groups,dc=ibm,dc=com personAccountRdnProperties=uid groupRdnProperties=cn federated.ldap.attributes.mapping.ldapName=mail, title federated.ldap.attributes.mapping.portalName=ibm-primaryEmail, ibm-jobTitle

   
   
2. After creating and configuring this file, move it to your WebSphere Portal machine and then run the ConfigEngine tasks in Listing 5a or 5b.
   
   Listing 5a. ConfigEngine tasks, part 1 (Linux)
   

   ./ConfigEngine.sh -DparentProperties=<file location> -DsaveParentproperties=true ./ConfigEngine.sh validate-federated-ldap ./ConfigEngine.sh wp-create-ldap ./ConfigEngine.sh wp-set-entitytypes

   
   
   
   Listing 5b. ConfigEngine tasks, part 1 (Windows)
   

   ConfigEngine.bat -DparentProperties=<file location> -DsaveParentproperties=true ConfigEngine.bat validate-federated-ldap ConfigEngine.bat wp-create-ldap ConfigEngine.bat wp-set-entitytypes

   
   
3. Restart the portal server and continue with the tasks in Listings 6a or 6b.
   
   Listing 6a. ConfigEngine tasks, part 2 (Linux)
   

   ./ConfigEngine.sh wp-validate-federated-ldap-attribute-config ./ConfigEngine.sh wp-update-federated-ldap-attribute-config

   
   
   
   Listing 6b. ConfigEngine tasks, part 2 (Windows)
   

   ConfigEngine.bat wp-validate-federated-ldap-attribute-config ConfigEngine.bat wp-update-federated-ldap-attribute-config

   
   
4. Once the LDAP has federated, it is possible your user login will have become ambiguous if there exists more than one user with the same login in both the LDAP and portal. To fix this, use a fully qualified user name to log in. Open a browser to the WebSphere Application Server administration console, log in, and navigate to Security > Global Security > Web and SIP security > Single sign-on (SSO) (Figure 1).
   
   Figure 1. Authentication mechanisms and expiration
   
   
   
5. Make sure the domain name is the same as what you are using with the Liberty profile and set the LTPA cookie names as shown with the Interoperability mode on. Once done, click OK and Save the changes.
   
   Figure 2. Single Sign-on (SSO) properties
   
   
   
6. Copy the LTPA keys that are located on the Worklight server to your local machine, as they will need to be imported to WebSphere Portal. The LTPA keys file on the Worklight server is located at:
   • Linux: <WorklightInstallDirectory>/server/wlp/usr/servers/worklightServer/resources/security/ltpa.keys
   • Windows: <WorklightInstallDirectory>\WAS85liberty-server\server\wlp\usr\servers\worklightServer\resources\security\ltpa.keys
7. Next, within the WebSphere Application Server administration console, navigate back to Security > Global Security. On the Global Security page above Web and SIP security, LTPA displays at the top of the Authentication section (Figure 1). At the bottom of the form on that page, type the password WebAS, which is the default for the Liberty profile key if you are importing that one. If using your own key, enter the appropriate password. For Fully qualified key file name, type the path and file name to the ltpa.keys file (Figure 3). Once done, click Import keys and Save the changes again. .
   
   Figure 3. Global security
   
   
   
8. Now restart the WebSphere Portal server.

Back to top

Setup Worklight application

Now you can create your Worklight application by creating the WAR file for the Liberty server and the actual client side application.

1. Open the Worklight development environment and Create a new Hybrid Application with a project name of SSODemo and an application name of SSODemoApp. Then add a new Android environment to this project. Your Project area should look like Figure 4.
   
   Figure 4. Project folders
   
   
   
2. To get a WAR file properly configured for your Liberty server, you first need to modify the worklightServerRootURL in the application-description.xml while in the Design view to point where the Worklight server will be on your Liberty profile server, such as http://host.domain.com:9080/SSODemo. Notice that the path includes the name of the project, as you will be deploying your Worklight WAR file to this path.
   
   Figure 5. Sever root URL
   
   
   
3. Under SSODemo/server/conf/worklight.properties, you want to un-comment and change the values shown in Listing 7.
   
   Listing 7. Worklight server properties
   

   publicWorkLightHostname=host.domain.com publicWorkLightProtocol=http publicWorkLightPort=9080 publicWorkLightContext=/SSODemo wl.db.jndi.name=jdbc/WorklightDS wl.db.type=DERBY wl.db.url=jdbc:derby:${worklight.home}/derby/WorklightDB;create=true wl.reports.db.url=jdbc:derby:${worklight.home}/derby/WorklightReportsDB;create=true

   
   
4. Save the file and then open SSODemo/server/conf/authenticationConfig.xml in Source view. Before the <realms> element, add the <securityTests> XML as shown in Listing 8.
   
   Listing 8. Security tests
   

   <securityTests> <mobileSecurityTest name="mobileTests"> <testDeviceId provisioningType="none" /> <testUser realm="WASLTPARealm" /> </mobileSecurityTest> <customSecurityTest name="WASLTPARealmTests"> <test realm="WASLTPARealm" isInternalUserID="true"/> </customSecurityTest> </securityTests>

   
   
5. Uncomment the security realm shown in Listing 9 that is labeled For websphere.
   
   Listing 9. Security realm For WebSphere
   

   <!-- For websphere --> <realm name="WASLTPARealm" loginModule="WASLTPAModule"> <className>com.worklight.core.auth.ext.WebSphereFormBasedAuthenticator </className> <parameter name="login-page" value="/login.html"/> <parameter name="error-page" value="/loginError.html"/> </realm>

   
   
6. Uncomment the login module For websphere (Listing 10).
   
   Listing 10. Login module for WebSphere
   

   <!-- For websphere --> <loginModule name="WASLTPAModule"> <className>com.worklight.core.auth.ext.WebSphereLoginModule</className> </loginModule>

   
   
7. Return to the SSODemo/apps/SSODemoApp/application-descriptor.xml file in the Design view. Under the main application, you want to add a security test of WASLTPARealmTests under the Common (optional) section (Figure 6).
   
   Figure 6. Security test for main application
   
   
   
8. In Android phones and tablets under Details, add the Security test of mobileTests.
   
   Figure 7. Android security test
   
   
   
9. Save the file and the WAR file is automatically generated into the bin folder. Copy the WAR file that was created to another location for editing. The WAR file is located at: <workspace>/bin/SSODemo.war.
10. The WAR file needs a few tweaks in order to fully enable the authentication to the Liberty profile server. You need a simple login.html and a loginError.html to put in the war file. Create these files with the content shown in Listings 11 and 12.
    
    Listing 11. login.html file contents
    

    <html> <head> <title>Login</title> </head> <body> <form method="post" action="j_security_check"> <label for="j_username">User name:</label> <input type="text" id="j_username" name="j_username" /> <br /> <label for="j_password">Password:</label> <input type="password" id="j_password" name="j_password" /> <br /> <input type="submit" id="login" name="login" value="Log In" /> </form> </body> </html>

    
    
    
    Listing 12. loginError.html file contents
    

    <html> <head></head> <body> Login Error </body> </html>

    
    
11. Open the SSODemo.war file with an archive manager and add both of these HTML files into the top level directory of the WAR (Figure 8).
    
    Figure 8. login.html and loginError.html added to WAR file
    
    
    
12. Next, navigate to the WEB-INF folder of the WAR and edit the web.xml file, highlighted in Figure 9, to include the XML in Listing 13 at the bottom right, before the web-app closing tag.
    
    Figure 9. web.xml location in WAR file
    
    
    
    
    Listing 13. web.xml login-config XML
    

    <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/login.html</form-login-page> <form-error-page>/loginError.html</form-error-page> </form-login-config> </login-config>

    
    
13. Upload this modified WAR file to your Liberty profile server into the <WorklightInstallDirectory>/server/wlp/usr/servers/worklightServer/apps directory.
14. Modify the Liberty profile server.xml for the Worklight Server again to include this new application. Find the file at:
    • Linux: <WorklightInstallDirectory>/server/wlp/usr/servers/worklightServer/server.xml
    • Windows: <WorklightInstallDirectory>\WAS85liberty-server\server\wlp\usr\servers\worklightServer\server.xml
15. After the declaration of the applicationcenter application, add the new application tag shown in Listing 14.
    
    Listing 14. Adding application to server.xml
    

    <application id="ssodemo" location="SSODemo.war" name="SSODemo" type="war"> <classloader delegation="parentLast"> <commonLibrary> <fileset dir="${shared.resource.dir}/lib" includes="worklight-jee-library.jar"/> </commonLibrary> </classloader> </application>

    
    
16. The Liberty profile server should now be fully configured to handle the client side code you will develop in the next section. Navigate to <WorklightInstallDirectory>/server/wlp/bin and then run this command to start the server:
    • Linux: sudo ./server start worklightServer
    • Windows: server.bat start worklightServer
17. Go to the Worklight console at http://host.domain.com:9080/SSODemo/console/.

Back to top

Setup the client side app

Now that the server WAR file is created, a few changes need to be made to get the Worklight app to properly compile in the development environment. This is because not all the packages get compiled unless the app deploys successfully to the internal Jetty server, which does not have the WebSphere classes necessary for login and so fails.

1. Return to the worklight.properties file and re-comment out all the lines modified in Listing 7 so that it looks like Listing 15.
   
   Listing 15. Worklight server properties
   

   #publicWorkLightHostname=host.domain.com #publicWorkLightProtocol=http #publicWorkLightPort=9080 #publicWorkLightContext=/SSODemo #wl.db.jndi.name=jdbc/WorklightDS #wl.db.type=DERBY #wl.db.url=jdbc:derby:${worklight.home}/derby/WorklightDB;create=true #wl.reports.db.url=jdbc:derby:${worklight.home}/derby/WorklightReportsDB; create=true

   
   
2. Go to authenticationConfig.xml and re-comment out the for websphere sections that were un-commented earlier, as shown in Listings 16 and 17.
   
   Listing 16. Security realm For WebSphere
   

   <!-- For websphere --> <!--realm name="WASLTPARealm" loginModule="WASLTPAModule"> <className>com.worklight.core.auth.ext.WebSphereFormBasedAuthenticator </className> <parameter name="login-page" value="/login.html"/> <parameter name="error-page" value="/loginError.html"/> </realm-->

   
   
   
   Listing 17. Login module For WebSphere
   

   <!-- For websphere --> <!--loginModule name="WASLTPAModule"> <className>com.worklight.core.auth.ext.WebSphereLoginModule</className> </loginModule-->

   
   
3. Add a fake realm and login module, as shown in Listings 18 and 19.
   
   Listing 18. Adding WASLTPA fake realm
   

   <realm loginModule="WASLTPAModule" name="WASLTPARealm"> <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className> </realm>

   
   
   
   Listing 19. Adding WASLTPA fake login module
   

   <loginModule name="WASLTPAModule"> <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className> </loginModule>

   
   Changing the security realms used would require following the section above on creating the WAR file again, and then following these last few steps again to revert the WebSphere modules once finished.
4. Add the HTML required for the application: SSODemo/apps/SSODemoApp/common/SSODemoApp.html. Change the body of the HTML to consist of the code segment shown in Listing 20.
   
   Listing 20. SSODemoApp.html body HTML
   

   <body id="content" style="display: none"> <div id="AppBody"> <div class="wrapper"> <iframe id="portalframe" src="" style="border:'0px none'" width="100%” height="640px"></iframe> </div> </div> <div id="AuthBody" style="display: none"> <div id="loginForm"> Username:<br/> <input type="text" id="usernameInputField" autocorrect="off" autocapitalize="off" /><br /> Password:<br/> <input type="password" id="passwordInputField" autocorrect="off" autocapitalize="off"/><br/> <input type="button" id="loginButton" value="Login" /> <input type="button" id="cancelButton" value="Cancel" /> </div> </div> <script src="js/initOptions.js"></script> <script src="js/SSODemoApp.js"></script> <script src="js/messages.js"></script> <script src="js/challengeResponse.js"></script> </body>

   
   This adds two sections to the body: a content area and an authentication area. Currently, the content area is simply an IFrame that will open up the portal page once authenticated to Worklight, showing that the SSO worked.

   Additionally this added the script tag for js/challengeResponse.js, which is a new file to be created that handles the client side aspect of needing to handle logins. This code is available for download, and is largely based off the challenge handler created in the Module 20.1 Form-based Authentication, with some modifications to permit checking the encrypted cache for stored login to accommodate automatic authentication. If no login is found, it then permits the user to login, and stores the information for later use for the automatic authentication. Figure 10 shows where the challengeResponse.js file should be located.

   
   
   Figure 10. Location of challengeResponse.js
   
   
   

   When a security challenge is detected and sent to the handleChallenge function in this challengeResponse.js file, it calls the busy indicator to inform the user that processing is occurring while the encrypted cache is opened to check for credentials. The encrypted cache works entirely through asynchronous calls with callback handlers. This means that each check needs to happen within those callbacks. If both the username and password have values set in the encrypted cache, it then creates a form submission for this information to log the user in. If a login isn't found, it shows the authentication body so the user can type the information manually and login, with the credentials now being stored for future use when the user clicks submit.

   When login is complete, the application body can be shown along with the IFrames source changed to load your portal. The portal is loaded after successful login; otherwise, it would load without the proper LTPA tokens for SSO, as authentication hasn't completed on page load, and these authentication challenges are done through XHR and not full page loads.

5. Once finished adding the challengeResponse.js file, right click the Android environment and select Run As > Build All and Deploy to create a new wlapp file to deploy on the Worklight server. Open the Worklight console for your server http://worklight.domain.com:9080/SSODemo/console/ and then choose file at the top where you have the option to Deploy application or adapter, and navigate to your Worklight SSODemo workspace. In the bin folder, there will be a file SSODemoApp-all.wlapp. Choose this file, and then Submit it. The application should now be deployed and appear like Figure 11.
   
   Figure 11. SSODemo app deployed
   
   
   
6. Back in your development environment, find the project that the Android environment added, called SSODemoSSODemoAppAndroid. Right-click and select Run As > Android Application.
7. Once the emulator or physical device has loaded the application, a login panel should display. Log in using a user from the LDAP. Your portal's front page should be logged in as that same LDAP user. When the application is closed and then reopened later, you should notice that the user is automatically logged in.

Back to top

Conclusion

This article described how to create a hybrid Worklight application that is capable of automatically logging in a user, and using a single sign-on to permit that user access your WebSphere Portal server without requiring an additional login. This enables a convenience many mobile users are accustomed to where their account is easily accessed and used upon opening the application.

Possible ways to expand on this exercise would be to add the ability for the user to remove their credentials so they could use a different log in. This could be done by simply removing the values from the encrypted cache when the user requests it, and reloading the page, triggering a new login. Another area would be to detect if a user's login is no longer valid due to the error message returned upon login failure, and removing the cache values so the user can sign in again with new values.

Back to top

Download

Information about download methods

Resources

Learn

• All articles in this series
  
  
• IBM Mobile Foundation
  
  
• IBM Worklight product information
  
  
• IBM Worklight user documentation
  
  
• Getting started with IBM Worklight
  
  
• WebSphere Portal product information
  
  
• IBM WebSphere Portal 8 Product Documentation
  
  
• Developing an Exceptional Web Experience
  
  
• Responsive Web Design
  
  
• Android Training: Using Hardware Devices
  
  
• IBM WebSphere Portal 8 API and SPI Reference
  
  
• Apache Cordova API Reference
  
  
• IBM developerWorks Mobile development zone
  
  
• IBM developerWorks WebSphere Portal zone
  
  
• IBM developerWorks WebSphere
  
  

Get products and technologies

• IBM Worklight Developer Edition 5.0
  
  
• Eclipse
  
  
• Android SDK
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Setup Liberty profile server
• Setup WebSphere Portal server
• Setup Worklight application
• Setup the client side app
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers