Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V6.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 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 V6.0 and later. Another version of this article is available for IBM Worklight V5.x.

Share:

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.



23 October 2013

Also available in Russian Japanese

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

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

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 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
  3. 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
  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. 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>
  3. 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>
  4. In the security realm that was just uncommented, add two more parameters after the login-page and error-page parameters (Listing NEW).
    Listing 11. Add parameters
    <parameter name="cookie-domain" value=".some.domain.com"/>          
    <parameter name="cookie-name" value="LtpaToken2"/>
  5. 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>
  6. 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 5. Security test for main application
    Figure 5. Security test for main application
  7. In Android phones and tablets under Details, add the Security test of mobileTests.
    Figure 6. Android security test
    Figure 6. Android security test
  8. 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.
  9. 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>
  10. 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
    Figure 7. login.html and loginError.html added to WAR file
  11. 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
    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>
  12. 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:
    • Linux: <WorklightInstallDirectory>/WorklightServer/configuration-samples/configure-liberty-derby.xml
    • Windows: <WorklightInstallDirectory>\WorklightServer\configuration-samples\configure-liberty-derby.xml
  13. Make a copy of this file called configure-ssodemo.xml.
  14. 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"/>

  15. 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.
  16. Run the following ant tasks to deploy your WAR to the server:

    ant -f configure-ssodemo.xml databases
    ant -f configure-ssodemo.xml install

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

  1. 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.
  2. 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.
  3. 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.
  4. 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
    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.

  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 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
    Figure 10. 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:


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.


Download

DescriptionNameSize
Code samplePart3-SSODemo-WLv6.zip62 KB

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, WebSphere
ArticleID=949369
ArticleTitle=Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V6.0, Part 3: Implementing automatic single sign-on with Worklight and WebSphere Portal
publish-date=10232013