Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V5.0, Part 3: Implementing automatic single sign-on with Worklight and WebSphere Portal

More and more, enterprises are providing multi-channel support to their web channel communities. This article explains how IBM WebSphere Portal and IBM Worklight V5.0 enable enterprises to create Worklight applications capable of automatically logging a user in upon startup, while also using single sign-on (SSO) to log the user into a WebSphere Portal server on the same host at the same time. This makes it easy for mobile apps to display portal pages customized to the user from within the application.

This article applies to IBM Worklight V5.x. Another version of this article is available for IBM Worklight V6.0.


Spencer Brooks, Front-end engineer, IBM

Spencer Brooks is a Front-end engineer at IBM's Research Triangle Park Development Lab. During his time in WebSphere Portal development he has primarily contributed to theme development.

07 August 2013 (First published 21 November 2012)

Also available in Chinese Russian Portuguese


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 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.

Setup Liberty profile server

Get Worklight now

Download IBM Worklight Developer Edition 6.0 now at no cost, and with no expiration date!

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. --> 
    <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"/> 
  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” 
        host=”<ldap host>” 
        ldapType=”IBM Tivoli Directory Server”>
  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=””/>

  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

Setup WebSphere Portal server

  1. To setup the WebSphere Portal server's LDAP, you will create an 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><host> 
    federated.ldap.bindPassword=<LDAP bind PW> 
    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)
    ./ -DparentProperties=<file location> -DsaveParentproperties=true 
    ./ validate-federated-ldap 
    ./ wp-create-ldap 
    ./ 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)
    ./ wp-validate-federated-ldap-attribute-config 
    ./ 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
    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
    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
    Figure 3. Global security
  8. 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.

  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
    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 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
    Figure 5. Sever root URL
  3. Under SSODemo/server/conf/, you want to un-comment and change the values shown in Listing 7.
    Listing 7. Worklight server properties
  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
        <mobileSecurityTest name="mobileTests"> 
            <testDeviceId provisioningType="none" /> 
            <testUser realm="WASLTPARealm" /> 
        <customSecurityTest name="WASLTPARealmTests"> 
            <test realm="WASLTPARealm" isInternalUserID="true"/> 
  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">
       <parameter name="login-page" value="/login.html"/> 
       <parameter name="error-page" value="/loginError.html"/> 
  6. Uncomment the login module For websphere (Listing 10).
    Listing 10. Login module for WebSphere
    <!-- For websphere --> 
    <loginModule name="WASLTPAModule"> 
  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
    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
    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
            <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" /> 
    Listing 12. loginError.html file contents
            Login Error 
  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
    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
    Figure 9. web.xml location in WAR file
    Listing 13. web.xml login-config XML
  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"> 
             <fileset dir="${shared.resource.dir}/lib" 
  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

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 file and re-comment out all the lines modified in Listing 7 so that it looks like Listing 15.
    Listing 15. Worklight server properties
  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">
    <parameter name="login-page" value="/login.html"/> 
    <parameter name="error-page" value="/loginError.html"/> 
    Listing 17. Login module For WebSphere
    <!-- For websphere --> 
    <!--loginModule name="WASLTPAModule"> 
  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">
    Listing 19. Adding WASLTPA fake login module
    <loginModule name="WASLTPAModule">

    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%”
        <div id="AuthBody" style="display: none"> 
            <div id="loginForm"> 
                <input type="text" id="usernameInputField" autocorrect="off" 
                    autocapitalize="off" /><br /> 
                <input type="password" id="passwordInputField" autocorrect="off" 
                <input type="button" id="loginButton" value="Login" /> 
                <input type="button" id="cancelButton" value="Cancel" /> 
        <script src="js/initOptions.js"></script> 
        <script src="js/SSODemoApp.js"></script> 
        <script src="js/messages.js"></script> 
        <script src="js/challengeResponse.js"></script> 

    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
    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 (and updating to the correct portal url and realm name; for example, "WASLTPARealm"), 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 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
    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.

Topology choices

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:


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.


Sample applicationPart3-SSODemo.zip46 KB



Get products and technologies


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Mobile development on developerWorks

Zone=Mobile development, WebSphere, Lotus
ArticleTitle=Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V5.0, Part 3: Implementing automatic single sign-on with Worklight and WebSphere Portal