Using WebSphere DataPower as a Security Gateway for Protecting Mobile Traffic

Product documentation


Abstract

DataPower Gateway Appliance is a security & integration gateway appliance, built for simplified deployment & hardened security, bridging multiple protocols & performing conversions at wire speed. IBM Worklight provides a powerful mobile application development platform for the enterprise. This article demonstrates how DataPower can be used in the DMZ of your enterprise to protect Worklight mobile application traffic.

Content

Introduction

As you mobile-enable your enterprise, there are several aspects of security to consider. When protecting mobile application traffic that is coming from your customer and employee devices into your network you want to protect the traffic from being altered, authenticate these users, and authorize their access to applications. In this article we showcase how to leverage the security gateway features of DataPower to protect mobile application traffic initiated by a client Worklight application.


Patterns for Integration

Enterprise topologies generally include designating different zones of protection so that specific processing can be secured and optimized. There are several ways DataPower can be leveraged in the DMZ and in other zones within your network to protect enterprise resources. As you start to build out Worklight applications to be delivered to the devices of your customers and employees these methods can be applied to mobile traffic. Here are some key methods observed:

    DMZ
    • Reverse Proxy Pattern - DataPower as a front-end Reverse Proxy and Security Gateway for your mobile applications built with and deployed on a Worklight Server
    • REST Service Façade Pattern - DataPower protecting REST endpoints in the DMZ without utilizing Worklight adaptors for integration.

    Intranet
    • Mediation Pattern - DataPower providing protocol and message transformation and security for enterprise services that are integrated via Worklight adapters and enabling connectivity to your existing SOA infrastructure.
    • Federated SSO with Authorization Pattern - DataPower to authorize authenticated access to OAuth protected resources
This article will focus on the Reverse Proxy Pattern. Subsequent articles will highlight and elaborate on these and other patterns as they emerge.


The Setup

In the following sections you will learn how to setup and use DataPower Multi-Protocol Gateway (MPGW) service to proxy and secure access to Worklight mobile applications. We are going to demonstrate using either HTTP basic authentication or HTTP form based login between the mobile client and DataPower. DataPower will authenticate the user and generate a LTPA SSO token to be used for the back-end WebSphere Application Server. See Figure 1.


Figure 1 : DataPower will authenticate the user and protect the communication to the Worklight Server

The following diagram shows a typical interaction between the user/application and the server.



In order to establish this pattern it is recommended you follow these steps:

  1. Install and configure a Worklight environment and test the install with a simple application without DataPower acting as the reverse proxy to make sure your application logic works.
  2. Configure a MPGW on DataPower to proxy the mobile application (or the Worklight console). The configuration of the gateway for these two patterns is described below.
    • Utilize Basic Authentication for end user authentication with AAA, and generate Single Signed On (SSO) LTPA token for Worklight Server, running on WebSphere Application Server if user has successfully authenticated.
    • Utilize HTML Form Based Login with AAA, and generate Single Signed On (SSO) LTPA token for Worklight Server, running on WebSphere Application Server if user has successfully authenticated.
  3. Testing with a reverse proxy will involve the following.
    • Updating the Worklight configuration on the server with the reverse proxy configuration (see below)
    • Update the mobile application mobile security test configuration to use form based authentication , which means the application requires to authenticate immediately upon startup. Either HTTP Basic Authentication or HTML Form Based Login is supported before the application starts. For web widgets, widget resources are only accessible to the browser after user has successfully authenticated.


Worklight Specific Configuration Setup

This section assumes you already have installed Worklight Studio and your stand-alone server environment on Liberty or WebSphere Application Server.

Adding the reverse proxy involves taking actions on each of the applications you are configuring. You need to modify the authenticationConfig.xml on the server to include the WASLTPAofRealm, login module, and security test. Use the WASLTPA realm to indicate that all the of applications within this realm will use LTPA tokens for their SSO and it would be configured like the following:

<securityTests>
    <mobileSecurityTest name="WASTest-securityTest">
      <testDeviceId provisioningType="none"/>
      <testUser realm="WASLTPARealm"/>
    </mobileSecurityTest>
    <webSecurityTest name="WASTest-web-securityTest">
      <testUser realm="WASLTPARealm"/>
    </webSecurityTest >
</securityTests>

<realms>
    <!-- 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>
</realms>

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

Note: This file is typically available at <WAS_INSTALL_DIR>/profiles/<WAS_PROFILE>/installedApps/<WAS_CELL>/IBM_Worklight_Console.ear/worklight.war/WEB-INF/classes/conf.

You will need to restart the Worklight console enterprise application after you make this change.


Client Mobile Application Update

In your client mobile application, add the following JavaScript to your HTML Worklight application. See the attached sample for the exact location and the JavaScript (JS) file.

function showLoginScreen() {
    $("#index").hide();$("#authPage").show();
}

function showMainScreen() {
    $("#authPage").hide();
    $("#index").show();
}

var myChallengeHandler = WL.Client.createChallengeHandler("WASLTPARealm");
var lastRequestURL;

myChallengeHandler.isCustomResponse = function(response) {
    //A normal login form has been returned
    var findError = response.responseText.search("DataPower/Worklight Error");
    if (findError >= 0)
    {
      return true;
    }
    //A normal login form has been returned
    var findLoginForm = response.responseText.search("DataPower/Worklight Form Login");
    if (findLoginForm >= 0)
    {
      lastRequestURL = response.request.url;
      return true;
    }
    //This response is a worklight server response, handle it normally
    return false;
};

myChallengeHandler.handleChallenge = function(response) {
    showLoginScreen();
};

myChallengeHandler.handleFailure = function(response) {
    console.log("Error during WL authentication.");
};

myChallengeHandler.submitLoginFormCallback = function(response) {
    var isCustom = myChallengeHandler.isCustomResponse(response);
    if (isCustom) {
      myChallengeHandler.handleChallenge(response);
    }
    else {
      //hide the login screen, we are logged in
      showMainScreen();
      myChallengeHandler.submitSuccess();
    }
};

//When the login button is pressed, submit a login form
$("#loginButton").click(function(){
    var reqURL = "/j_security_check";
    alert(lastRequestURL);
    var options = {method: "POST"};
    options.parameters = {
      j_username: $("#username").val(),
      j_password: $("#password").val(),
      originalUrl : lastRequestURL,
      login: "Login"
    };

    options.headers = {};
    myChallengeHandler.submitLoginForm(reqURL, options,
      myChallengeHandler.submitLoginFormCallback);
});

If you want to retrieve the LTPA key file used for authentication from the Worklight Server, you can also use the WL.Client.Login Worklight API function.
    WL.Client.login(“WASLTPARealm”);

This call will trigger the myChallengeHandler.isCustomResponse method with a JSON response, where you can retrieve the LTPA key file.
    if (response.responseJSON.WASLTPARealm &&
      response.responseJSON.WASLTPARealm.isUserAuthenticated)
    var sessionKey = response.responseJSON.WASLTPARealm.attributes.LtpaToken;

For any subsequent Adapter calls that need to be proxied through the reverse proxy, you can include this sessionKey as a header within the request.

Ensure your HTML body for the Worklight application reflects the login information that DataPower will handle. The Worklight documentation and samples explain the use of authentication and customizing authentication (20-22).


It can be as simple as the following:

<div id= "authPage">
    You are not authenticated.
    <div id= "loginForm">
      Username:<br/>
      <input type= "text" id= "username" autocorrect= "off" autocapitalize= "off"
        value= "admin"/><br/>
      Password:<br/>
      <input type= "password" id= "password" autocorrect= "off" autocapitalize= "off"
        value= "admin"/><br/>
      <input type= "button" id= "loginButton" value= "Login" />
    </div>
</div>

<div id= "index">
    You are authenticated.
</div>


Application-descriptor.xml

The Worklight documentation covers how to create both the client side app and the server side configuration files.



In order to have the authentication test added to an application or device, add a securityTest attribute to the environment's tag in the application-descriptor.xml in your project to use the WASTest-securityTest security test we created earlier in our authenticationConfig.xml on the server-side. Here is an iPad example:

<ipad bundleId= "com.Datapower" securityTest= "WASTest-securityTest" version= "1.0">
    <worklightSettings include= "true"/>
    <security>
      <encryptWebResources enabled= "false"/>
      <testWebResourcesChecksum enabled= "false"
        ignoreFileExtensions= "png, jpg, jpeg, gif, mp4, mp3"/>
    </security>
</ipad>

For an iPhone example, your application descriptor may look like the following.

<iphone bundleId= "com.myappId" version= "1.3.3" securityTest= "WASTest-securityTest ">
    <worklightSettings include= "true"/>
    <security>
      <encryptWebResources enabled= "false"/>
      <testWebResourcesChecksum enabled= "false" ignoreFileExtensions= "png, jpg, jpeg, gif, mp4, mp3"/>
    </security>
</iphone>


Define a MPGW on DataPower

Configuring a MPGW to terminate the secure network connection and enforce the authentication of an application as defined above follows the same steps. The steps and illustrations represent a subset of the configuration screens found in the DataPower GUI that are necessary to configure the MPGW for a mobile application. To configure the proxy we will need to configure the front-side and the back-end URL.

Start with the General Configuration tab (See Figure 2). The items to be selected are indicated in the illustration below with blue arrows and include:
  • Multi-Protocol Gateway Name: provide a name for your gateway
  • Set Response Type: Non-XML
    This allows http Web application traffic, include JSON, JavaScript, CSS to pass through the appliance.
  • Set Request Type: Non-XML
    This allows http web application request to be handled by appliance
  • Front Side Protocol: For the type of use case we describe we use an HTTPS handler. For this style of interaction the user credential will be passed between the client and server, so the transport should be protected using SSL protocol.
  • Multi-Protocol Gateway Policy: The Policy tab allows for additional configuration, and in this case we select '+' to add a new policy, which will contain the AAA policy. (This depends on the authentication method used. See section 3.a and 3.b for detail information on how to configure the appropriate policy.)
  • Backend URL: Specify the address and port of the Worklight server hosted on a WebSphere Application Server. (Given the credential, LTPA will be sent to the back-end, consider to use a SSL port, for this article, we will use an HTTP port.)



When creating a HTTPS front-side handler there are additional parameters to configure(see Figure 2.a and 2.b)
  • Name: Provide a name for the handler (HTTPS)
  • Port Number: Choose an available port
  • Allowed Methods and Versions: Enable 'Get Method'
    This enables support for HTTP Get.
  • SSL Proxy: Specify a SSL Reverse Proxy profile
    This provides the identity for the SSL Server.


Figure 2.a : Select HTTPS(SSL) Front Side Handler

…...


Figure 2.b Configure HTTPS Front Side Handler

The next step is to configure the Policies that you want to be applied to the traffic. Select the “General” Tab → Multi-Protocol Gateway Policy (by clicking '+'). In the policy section we need to configure a set of rules to be applied based on what actions the reverse proxy needs to enforce. DataPower allows the administrator to configure a policy, name it and then reuse it. This policy will handle both mobile web and mobile application traffic.

Here we give two options. Option 1 is HTTP Basic Authentication. Option 2 is for forms based authentication.

Option 1: Utilize HTTP Basic Authentication (see Figure 4)
  • Policy Name: Enter a policy name (“worklight-basicauth”), click “Apply Policy”
  • Click “New Rule”: (repeat this for 4 rules below, from top to bottom on Figure 4)
  • Rule 1 – When processing HTML content we want to skip processing with the icon associated with web site or web page (worklight-basicauth_rule_0)
    • Direction: “Client to Server” or “Both Directions”
    • Match: type = url, match pattern = /favicon.ico
    • Advanced: “Set Variable” → var://service/mpgw/skip-backside = 1
    • Result
  • Rule 2 – Since the policy will be applied to each request, the order of the rules needs to ensure that we first Verify a LTPA Token if it exists in the HTTPrequest (worklight-basicauth_rule_3). If there is no token, we then move to the next rule and authenticate the user (rule 3)
    • Direction: “Client to Server”
    • Match: type = http, HTTP Header Tag = Cookie, HTTP Value Match=*LTPAToken*
    • AAA: VerifyLTPA (See AAA section below on how to configure this)
      Output: NULL
    • Result
  • Rule 3 – Handle the authentication of end user if LTPA Token does not exist (worklight-basicauth_rule_1)
    • Direction: “Client to Server”
    • Match: type = url, match pattern = *
    • AAA: BasicAuth2LTPA (See AAA section below on how to configure this)
      Output: NULL
    • Result
  • Rule 4 - Handle both the redirect and content-type reset (potentially), on the response side (worklight-basicauth_rule_2)
    • Direction: “Server to Client”
    • Match: type = url, match pattern = *
    • Filter: provides a custom style sheet which handles redirect and content-type rewrite (a sample style sheet, redirect.xsl, is provided with this article) redirect.xslredirect.xsl
      Output: NULL
    • Result

Figure 4: MPGW Style Policy for HTTP Basic Authentication Support



Option 2: Utilize HTTP Form Based Login (see Figure 5)
  • Policy Name: Enter a policy name, (“mpgw-form”) click “Apply Policy”
  • Click “New Rule”: (repeat this for 5 rules below, from top to bottom on Figure 5)
  • Rule 1 – skip processing with the icon associated with web site or web page (mpgw-form_rule_0)
    • Direction: “Client to Server” or “Both Directions”
    • Match: type = url, match pattern = /favicon.ico
    • Advanced: “Set Variable” → var://service/mpgw/skip-backside = 1
    • Result
  • Rule 2 - Verify a LTPA Token if it exists in the http request (mpgw-form_rule_1)
    • Direction: “Client to Server”
    • Match: type = http, HTTP Header Tag = Cookie, HTTP Value Match=*LTPAToken*
    • AAA: VerifyLTPA (See AAA section below on how to configure this)
      Output: NULL
    • Result
  • Rule 3 - Generate the HTML Form Login Page (mpgw-form_rule_2)
    • Direction: “Client to Server”
    • Match: Match with PCRE = on,
      type = url, match pattern = /(Login|Error)Page\.htm(l)?(\?originalUrl=.*)?
    • Transform: provides a custom style sheet which builds either a Login or Error html page. (a sample style sheet, FormLogin.xsl, is provided with this article) FormLogin.xslFormLogin.xsl

    Note: The HTML Login Form policy allows you to specify whether you retrieve the login/error pages from DataPower or back-end application server. In this example, we have provided a style sheet of a login and error page; however, you could also use your mobile application login/error pages.

    Drag and drop the Advance action. Select the set-var action and specify the service variable, var://service/routing-url and value with the endpoint of your login page.
  • Rule 4 - Handle the authentication of end user if LTPA Token does not exist (mpgw-form_rule_3)
    • Direction: “Client to Server”
    • Match: type = url, match pattern = *
    • Advanced: “Convert Query Parameter to XML”. Choose default for other selections.
    • AAA: Form2LTPA (See AAA section below on how to configure this)
  • Rule 5 - Handle both the redirect and content-type reset (potentially), on the response side (mpgw-form_rule_6)
    • Direction: “Server to Client”
    • Match: type = url, match pattern = *
    • Filter: provides a custom style sheet which handles redirect and content-type rewrite (a sample style sheet, redirect.xsl, is provided with this article) redirect.xslredirect.xsl
      Output: NULL
    • Result


Figure 5: MPGW StylePolicy for HTML Form Basic support

Create AAA policy involves a series of Actions that become part of the policy rules above.



The Figure above illustrates the range of options available on DataPower. From these we select a subset to address the two integration options provided in this article.

    BasicAuth2LTPA
    • Extract Identity: Method : Select “HTTP Authentication Header” (See Figure 6.a)
    • Authenticate: Choose the authentication method, if WAS is using LDAP, configure LDAP here.
    • Extract Resource: Resource Information : Select “URL Sent by Client”
    • Postprocess :
      • Generate an LTPA Token
      • Specify “LTPA Token Expiry”, “LTPA Key File” and “LTPA Key File Password”

    Form2LTPA
    • Extract Identity: Method : Select “HTML Form-based Authentication”, and choose a HTML Form Policy (See Figure 6.b) See http://www.ibm.com/developerworks/websphere/library/techarticles/1208_poon1/1208_poon1.html#html for more detail on how to create a HTML Form Policy, one difference is the SSL connection (See Figure 5.b)
      • Use SSL For Login: enabled
      • SSL Port: this is the port that the MPGW is listening on

        Figure 5.b : Enable SSL in the HTML Form Policy
    • Authenticate: Choose the authentication method, if WAS is using LDAP, configure LDAP here.
    • Extract Resource: Resource Information : Select “URL Sent by Client”
    • Postprocess:
      • Generate an LTPA Token
      • Specify “LTPA Token Expiry”, “LTPA Key File” and “LTPA Key File Password”

    VerifyLTPA
    • Extract Identity: Method : Select “LTPA Token” (See Figure 6.c)
    • Authenticate: Choose “Accept an LTPA Token”, and specify “LTPA Token Versions”, “LTPA Key File” and “LTPA Key File Password” (See Figure 6.d)
    • Extract Resource: Resource Information : Select “URL Sent by Client”

    Figure 6.a HTTP Basic Authentication



    Figure 6.b HTML Form Based Authentication


    Figure 6.c LTPA Token Authentication




    Figure 6.d Verify an LTPA Token


Once you have completed the options on the General tab, there are additional options to select on the Advanced tab (See Figure 3)
  • Follow Redirect: off
    This prevents the DataPower back-end user agent from resolving redirects from the back-end. Web applications typically require a client browser to resolve redirects, so they can maintain the context for “directory” along with setting LTPA cookie on the client.

    Figure 3: Advanced Tab


Conclusion

In summary, Worklight mobile application traffic can be protected by using DataPower’s secure gateway functionality to enforce authentication on the DataPower device and forward the credentials (header or LTPA token) downstream to Worklight Server to establish the user identity as part of the mobile traffic. In a future article we will explore configuring other authentication and authorization use cases as well as explore the use of DataPower as a REST gateway and DataPower performing ESB security and protocol mediation.

Related information

See this content also in IBM Worklight Foundation V6.2.
See this content also in IBM Worklight V6.1.0

Cross reference information
Segment Product Component Platform Version Edition
Mobile- Speech and Enterprise Access IBM Mobile Foundation Documentation AIX, Apple iOS, BlackBerry OS, Google Android, HP-UX, Linux, Mac OS X, Solaris, Windows 5.0.6, 5.0.5.1, 5.0.5, 5.0.0.3, 5.0.0.2, 5.0.0.1, 5.0 Consumer, Enterprise
Mobile- Speech and Enterprise Access IBM Mobile Application Platform Pattern Documentation AIX, Linux Red Hat - xSeries 5.0.6 All Editions

Rate this page:

(0 users)Average rating

Document information


More support for:

IBM Worklight
Documentation

Software version:

5.0, 5.0.0.1, 5.0.0.3, 5.0.5, 5.0.5.1, 5.0.6

Operating system(s):

AIX, Apple iOS, BlackBerry OS, Google Android, HP-UX, Linux Red Hat - xSeries, Linux SUSE - xSeries, Mac OS X, Solaris, Windows

Software edition:

Consumer, Enterprise

Reference #:

7038292

Modified date:

2013-09-05

Translate my page

Machine Translation

Content navigation