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.
This article uses WebSphere Portal V8, and Worklight V6.0. 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.
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:
Make these changes inside the server.xml file:
- 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"/>
- 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>
- 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
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>
- 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”/>
- 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:
sudo ./server start worklightServer
server.bat start worklightServer
- Stop the server:
sudo ./server stop worklightServer
server.bat stop worklightServer
Setup WebSphere Portal server
- 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
- After creating and configuring this file, move
it to your WebSphere Portal machine and then run the ConfigEngine tasks in Listing 5 or 6.
Listing 5. 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 6. 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
- Restart the portal server
and continue with the tasks in Listings 7 or 8.
Listing 7. ConfigEngine tasks, part 2 (Linux)
./ConfigEngine.sh wp-validate-federated-ldap-attribute-config ./ConfigEngine.sh wp-update-federated-ldap-attribute-config
Listing 8. ConfigEngine tasks, part 2 (Windows)
ConfigEngine.bat wp-validate-federated-ldap-attribute-config ConfigEngine.bat wp-update-federated-ldap-attribute-config
- 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
- 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
Figure 2. Single Sign-on (SSO) properties
- 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:
- 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
- Now restart the WebSphere Portal server.
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.
- 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
- Open SSODemo/server/conf/authenticationConfig.xml in
Source view. Find the <securityTests> XML and add the mobile and web security tests as shown in Listing 9.
Listing 9. Security tests
<securityTests> ... <mobileSecurityTest name="mobileTests"> <testDeviceId provisioningType="none" /> <testUser realm="WASLTPARealm" /> </mobileSecurityTest> <webSecurityTest name="WASLTPARealmTests"> <testUser realm="WASLTPARealm"/> </webSecurityTest> ... </securityTests>
- Uncomment the security realm shown in Listing 10 that is labeled For websphere.
Listing 10. 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>
- In the security realm that was just uncommented, add two more
parameters after the login-page and error-page parameters (Listing
Listing 11. Add parameters
<parameter name="cookie-domain" value=".some.domain.com"/> <parameter name="cookie-name" value="LtpaToken2"/>
- Uncomment the login module For websphere (Listing 12).
Listing 12. Login module for WebSphere
<!-- For websphere --> <loginModule name="WASLTPAModule"> <className>com.worklight.core.auth.ext.WebSphereLoginModule</className> </loginModule>
- 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
Figure 5. Security test for main application
- In Android phones and tablets under Details, add the Security test of
Figure 6. Android security test
- 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.
- 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 13. 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 14. loginError.html file contents
<html> <head></head> <body> Login Error </body> </html>
- 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 7).
Figure 7. login.html and loginError.html added to WAR file
- Next, navigate to the WEB-INF folder of the WAR and edit the web.xml
file, highlighted in Figure 8, to include the XML in Listing 15 at the bottom right, before the web-app closing tag.
Figure 8. web.xml location in WAR file
Listing 15. 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>
- To deploy the Worklight WAR file to the server, locate the sample
XML file for deploying to a Liberty profile server with a Derby
database, located at:
- Make a copy of this file called configure-ssodemo.xml.
- Open the copy of the XML file and locate the property that
indicates where your project WAR is located:
<property name="worklight.project.war.file" value=”<path to WAR>/SSODemo.war"/>
- You might also need to update other properties as needed to point to your correct installation directories for Worklight, Liberty, and Derby. Additionally, the name of the Liberty profile, such as "worklightServer" will need updated.
- Run the following ant tasks to deploy your WAR to the server:
ant -f configure-ssodemo.xml databases
ant -f configure-ssodemo.xml install
- 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:
sudo ./server start worklightServer
server.bat start worklightServer
- Go to the Worklight console at http://host.domain.com:9080/worklight/console/.
Setup the client side app
Now that the server WAR file is created, the client that will authenticate through these methods can be created.
- 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.
- 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 16.
Listing 16. SSODemoApp.html body HTML
<body id="content" style="display: none"> <div id="AppBody"> <div class="wrapper"> </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.
- Update the initOptions.js file located at apps/SSODemoApp/common/js/initOptions.js and look for the connectOnStartup value and make sure it is set to true.
- 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
(updated for V6), and
is largely based off the challenge handler created in the 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 9 shows where the challengeResponse.js file should be located.
Figure 9. 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 and redirected 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.
- Once finished adding the challengeResponse.js file (and updating to the correct portal url and realm name; for example, "WASLTPARealm"), right click the
Android environment and select Run As > Build For Remote
Server... and point it your Worklight console that you
installed earlier; for example,
http://worklight.domain.com:9080 with a context root of
"/worklight." This will create a new wlapp file to deploy on the Worklight
server. Open the Worklight console for your server
http://worklight.domain.com:9080/worklight/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 10.
Figure 10. SSODemo app deployed
- Back in your development environment, find the project that the Android environment added, called SSODemoSSODemoAppAndroid. Right-click and select Run As > Android Application.
- 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.
There are server topology options to consider when planning your Worklight and WebSphere Portal deployment. A proxy server or HTTP server might be required for IBM Worklight Server and WebSphere Portal. A proxy server or HTTP server will be needed to deploy this sample when the servers are not on the same system and you need to have one URL (common hostname for WebSphere Portal and Worklight) shared with the user. Worklight education module 45 discusses how to use a remote website, such as one hosted on a WebSphere Portal server.
In addition, the main purpose of this server instance is to act as a surrogate that can route requests to back end server clusters using routing rules and load balancing schemes. Both an HTTP server configured with the HTTP plug-in and the WebSphere Application Server proxy server can be used to load balance requests being serviced by WebSphere Application Servers, clusters, or web servers.
If you require a webserver (plugin-in) to be configured with the WebSphere Application Server Liberty profile to route across multiple hosts, refer to the Information Center document on Configuring a web server plug-in for the Liberty profile.
There are differences between using a proxy and an HTTP plug-in and to learn the advantages of either solution, see the article Proxy server versus the HTTP plug-in - Choosing the best WebSphere Application Server workload management option.
For more information on installing and configuring a web server plug-in or proxy, see these resources:
- Setting up the proxy server
- Installing a DMZ Secure Proxy Server for IBM WebSphere Application Server
- Configuring a DMZ Secure Proxy Server using the administrative console
- Installing IBM HTTP Server
- Configuring IBM HTTP Server
- Installing Web server plug-ins
- Plug-ins configuration
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.
|Code sample||Part3-SSODemo-WLv6.zip||62 KB|
- 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