Integrating with DataPower as a security gateway and reverse proxy

Learn how to integrate with IBM® WebSphere® DataPower® as a reverse proxy and security gateway.

Before you begin

Note: To integrate your application with DataPower by using LTPA and DataPower HTML forms-based authentication, follow the specialized procedure at Integrating with DataPower as a reverse proxy using LTPA and form-based authentication. The specialized procedure includes a DataPower configuration pattern that eliminates much of the manual configuration described in the following generic procedure, including the need for the manual rule definitions outlined in the topic DataPower configuration rules.
  • Read the topic Integration with IBM WebSphere DataPower as a security gateway and reverse proxy.
  • Install IBM WebSphere DataPower by following the instructions in the WebSphere DataPower documentation.
  • Install IBM MobileFirst™ Platform Foundation with interim fix 7.1.0.00-20160513-1006 or later.
    Ensure that the installation includes MobileFirst Studio.
  • Establish a stand-alone MobileFirst Server environment that uses WebSphere Application Server.

Procedure

  1. Configuring your MobileFirst applications
    1. For each application that you are configuring, modify the authenticationConfig.xml file on the server to include the following security test, realm, and login module declarations:
      <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>

      By default, the authenticationConfig.xml file is usually available in this directory: <WAS_INSTALL_DIR>/profiles/<WAS_PROFILE>/installedApps/<WAS_CELL>/IBM_Worklight_Console.ear/worklight.war/WEB-INF/classes/conf.

    2. Restart the MobileFirst Operations Console enterprise application.
  2. Update your client mobile app.
    1. In your client mobile app, add the following JavaScript code to your HTML MobileFirst application:
      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 MobileFirst Server response, handle it normally
        return false;
      };
      
      myChallengeHandler.handleChallenge = function(response) {
        showLoginScreen();
      };
      
      challengeHandler1.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, you 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);
      
      });
    2. If you want to retrieve the LTPA key file that is used for authentication from MobileFirst Server, you can also use the login method of the MobileFirst WL.Client class: WL.Client.login("WASLTPARealm");

      This call triggers the myChallengeHandler.isCustomResponse method with a JSON response from which 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 call that needs to be proxied through the reverse proxy, you can include the extracted LTPA key file (stored in the sessionKey variable in the code sample) as a header within the request.

      Ensure that the HTML body for your MobileFirst application reflects the login information that is to be handled by DataPower.

    3. To add the authentication test to an application or device, add a securityTest attribute to the environment tag in the project application-descriptor.xml file.

      Set the value of this attribute to the name of the security test that you declared in the authenticationConfig.xml file in substep 1a.

      Here is an iPad example:
      <ipad bundleId="com.Datapower" securityTest="WASTest-securityTest" version="1.0">
        <worklightSettings include="false"/>
        <security>
          <encryptWebResources enabled="false"/>
          <testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3"/>
        </security>
      </ipad>
  3. Define a multiprotocol gateway.
    1. In the IBM DataPower WebGUI, in the search box under Control Panel, enter Multi-Protocol and select New Multi-Protocol Gateway.
    2. On the General Configuration page, define the following settings:
      Table 1. General Configuration
      Field Description
      Multi-Protocol Gateway Name Provide a name for your gateway.
      Response Type Select Non-XML. With this value, HTTP web application traffic (including JSON, JavaScript, and CSS) passes through the appliance.
      Request Type Select Non-XML. With this value, HTTP web application requests are handled by the appliance.
      Front Side Protocol

      Select HTTPS (SSL). For this type of interaction in which user credentials are passed between client and server, HTTPS is appropriate. Also provide the following front-side handler details:

      Name
      Enter a name for the configuration.
      Port Number
      Enter a number for the listening port. This port number must match the port number that you specify if you define an AAA policy that uses HTML forms-based authentication. See Table 3.
      Allowed Methods and Versions
      Select GET method to enable support for HTTP Get.
      SSL Proxy
      Select an SSL Reverse Proxy profile to identify the SSL server.
      Multi-Protocol Gateway Policy

      Click +, and then create rules to define the policies that are listed in the following topics, depending on the type of authentication that you decide to use:

      Backend URL Specify the address and port of the MobileFirst Server that is hosted on WebSphere Application Server.
  4. Create an AAA policy that supports the HTTP basic authentication or HTML forms-based login policy that you defined in the previous step.
    1. In the IBM DataPower WebGUI, in the search box under Control Panel, enter AAA, and then click Add.
    2. Depending on the type of authentication that you want to use, define the following settings.
      • For HTTP basic authentication, specify the settings as listed in the following table.
        Table 2. AAA policy for HTTP basic authentication
        Phase Description
        Extract Identity In the Methods field, select HTTP Authentication Header.
        Authenticate Choose the authentication method. If WebSphere Application Server is using LDAP, configure LDAP here.
        Extract Resource Select URL Sent by Client.
        Post processing Generate an LTPA token. Specify LTPA Token Expiry, LTPA Key File, and LTPA Key File Password.
      • For HTML forms-based authentication, specify the settings as listed in the following table.
        Table 3. AAA policy for HTML forms-based authentication
        Phase Description
        Extract Identity In the Methods field, select HTML Forms-based Authentication. Select or create an HTML forms-based policy that has the Use SSL for Login option enabled, assigns SSL Port to the port number on which the MPGW is listening (that was specified in step 3), and has the Enable Session Migration option disabled.
        Authenticate Choose the authentication method. If WebSphere Application Server is using LDAP, configure LDAP here.
        Extract Resource Select URL Sent by Client.
        Post processing Generate an LTPA token. Specify LTPA Token Expiry, LTPA Key File, and LTPA Key File Password.
  5. On the Advanced page, specify the advanced settings as listed in the following table.
    Table 4. Advanced settings
    Field Value
    Persistent Connections On.
    Allow Cache-Control Header Off
    Loop Detection Off
    Follow Redirects Off. This value 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 that they can maintain the context for “directory” along with setting an LTPA cookie on the client.
    Allow Chunked Uploads Off
    MIME Back Header Processing Off
    MIME Front Header Processing Off

Results

Your MobileFirst application traffic is now protected by a secure DataPower gateway. User authentication is enforced by the DataPower appliance, which forwards the user credentials to MobileFirst Server either as an HTTP header or as an LTPA token, depending on the selected authentication method.