Integrating with DataPower as a reverse proxy using LTPA and form-based authentication

Use the provided MobileFirst samples and IBM® WebSphere® DataPower® configuration pattern and to integrate your application with a DataPower gateway that uses lightweight third-party authentication (LTPA) and HTML forms-based authentication.

• Configuring your MobileFirst client application
  1. Create a MobileFirst application with your required application logic. See Developing MobileFirst applications. Start with a simple application that does not include security tests, and run the application to test your installation. You can also start out by using the sample project from the MobileFirst LTPA DataPower integration package.
  2. Add a challenge handler to your client application: When the application attempts to access a protected resource, the sample MFP_LTPA_Integration DataPower pattern sends a login forum to the application. Add a custom challenge handler to your application to detect the incoming login form by searching the response for a known string, such as j_security_check.
     The challenge-handler requirements for handling a DataPower login forum are the same as for handling MobileFirst form-based authentication. See Implementing form-based authenticators, Code the client side step. Note the following points:

     • The login forum's submit-action URL is /j_security_check.
     • The login forum that you submit back needs to contain j_username and j_password fields.

     The sample client application code in the MobileFirst LTPA DataPower integration package defines the required challenge handler for integrating with the sample DataPower MFP_LTPA_Integration pattern.

     Following is an explanation of the provided sample-application challenge handler, using the code from the sample hybrid application (DataPower/apps/HybridDataPower/common/js/main.js):
     The sample creates a challenge-handler object (DataPowerChallengeHandler); see the WL.Client.createChallengeHandler method:

     var DataPowerChallengeHandler = WL.Client.createChallengeHandler();

     Clicking the form-submission button in the login forum triggers a call to the submitLogingForm method of the challenge-handler object with the provided authentication credentials, which are stored in the j_username and j_password parameters:

     $('#AuthSubmitButton').bind('click', function () {
         busyIndicator.show();
         var reqURL = '/j_security_check';
         var options = {};
         options.parameters = {
             j_username : $('#AuthUsername').val(),
             j_password : $('#AuthPassword').val()
         };
         options.headers = {};
         DataPowerChallengeHandler.submitLoginForm(reqURL, options, DataPowerChallengeHandler.submitLoginFormCallback);

     When the login response returns, the security framework calls the challenge-handler's login-form submission callback method, submitLoginForumCallback. The callback method calls the handler's isCustomResponse method to check whether a custom login response was received. When this method returns true, the callback method calls the challenge handler's handleChallenge method:

     DataPowerChallengeHandler.isCustomResponse = function(response){
     	if (!response || response.responseText === null) {
             return false;
         }
         var indicatorIdx = response.responseText.search('j_security_check');
          
         if (indicatorIdx >= 0){
             return true;
         } 
         
         return false;
     };
     
     DataPowerChallengeHandler.submitLoginFormCallback = function(response) {
         var isLoginFormResponse = DataPowerChallengeHandler.isCustomResponse(response);
         if (isLoginFormResponse){
         	DataPowerChallengeHandler.handleChallenge(response);
         } else {
             $('#result').show();
             $('#auth').hide();
             DataPowerChallengeHandler.submitSuccess();
         }
     }

     The challenge handler's handleChallenge method can be used to display your custom login form, provided that #auth contains the HTML code for collecting the user credentials:

     DataPowerChallengeHandler.handleChallenge = function(response){
         $('#result').hide();
         $('#auth').show();
         busyIndicator.hide();
     };

  3. On Android, consider adding a workaround for failed requests due to circular redirects: A known limitation might cause some requests, such as post-logout requests, to fail on Android platforms with errors such as org.apache.http.client.CircularRedirectException: Circular redirect..... The workaround is to add the following call in the native Java™ code of your application before making any request:

     HttpClientManager.getInstance().getHttpClient().getParams().setBooleanParameter(ClientPNames.ALLOW_CIRCULAR_REDIRECTS, true);

     In native applications, you can use the following shorthand form instead:

     WLClient.getInstance().setAllowHTTPClientCircularRedirect(true);

     For example, in a hybrid application you can add the workaround code in the onInitWebFrameworkComplete method of the WLInitWebFrameworkListener interface. This method is called when the IBM MobileFirst Platform Foundation web initialization is completed and web resources are ready to be used:

     public void onInitWebFrameworkComplete(WLInitWebFrameworkResult result){
       if (result.getStatusCode() == WLInitWebFrameworkResult.SUCCESS) {
         HttpClientManager.getInstance().getHttpClient().getParams().setBooleanParameter(ClientPNames.ALLOW_CIRCULAR_REDIRECTS, true);
         super.loadUrl(WL.getInstance().getMainHtmlFilePath());
       } else {
         handleWebFrameworkInitFailure(result);
       }
     }

  4. On Android, using the send method of the WLResourceRequest class with a custom WLHttpResponseListener response listener is currently not supported in gateway topologies. If your application uses WLHttpResponseListener, call WLClient.connect or WLAuthorizationManager.obtainAuthorizationHeader before sending the resource request, to ensure that your challenge is handled.
• Configuring your MobileFirst Server
  1. Configure the user registry in your application-server configuration file (server.xml):
     1. Open the LTPA keys file of your application server: ltpa.keys. (This file is typically found in the <server_configuration_directory>/servers/worklight/resources/security directory of your MobileFirst Server.) Find the com.ibm.websphere.ltpa.Realm key in the file, and copy and save its value (for example, worklightRealm).
     2. Open the configuration file of your application server: server.xml. (This file is typically found in the <server_configuration_directory>/servers/worklight directory of your MobileFirst Server.) Look for a <basicRegistry> or <ldapRegistry> element in the file. If neither element exists, create the element that matches your required configuration (see the documentation of your application server).
     3. Set the realm attribute of your user-registry element to the value of the com.ibm.websphere.ltpa.Realm LTPA key that you copied and saved in Step 1.a (if it is not already set).
     4. When using the <basicRegistry> element, ensure that the element defines all the authorized users for your application. For example, the following basic-registry definition includes the credentials of two of the authorized users that are configured in the sample MFP_LTPA_Integration pattern:

        <basicRegistry realm="worklightRealm">
            <user name="admin" password="admin"/>
            <user name="fred" password="smith"/>
        </basicRegistry>

        Note: You need to set the password attribute of each contained <user> element, even though these passwords will not be used because DataPower will handle the credentials authentication.

        For LDAP configuration, see the documentation of your application server.

     Note: When moving from development to production or when connecting to an untrusted network, modify the authorized users or the authentication method of the sample pattern, and edit your server configuration to match the pattern. See the authorized-users credentials and authentication method customization note.
  2. Configure the authentication-configuration file of your MobileFirst Server: authenticationConfig.xml. (This file is typically found in the server/conf directory of your MobileFirst project.) DataPower will be responsible for authenticating the client, and will use LTPA to communicate the results to MobileFirst Server. However, to represent the user to DataPower you need to define a MobileFirst LTPA form-based authentication realm and LTPA login module. The realm must be of the LTPA authenticator class (com.worklight.core.auth.ext.WebSphereFormBasedAuthenticator) and use the WASLTPAModule login module for LTPA integration of the security framework with WebSphere Application Server. Then, define a security test that uses your realm. You will use this security test in the next step to protect your resources.
     The DataPower/server/conf/authenticationConfig.xml file of the sample MobileFirst DataPower integration project includes the required configurations that are explained here.
     • WASLTPAModule login module

       <loginModules>
           ...
           <loginModule name="WASLTPAModule" expirationInSeconds="30">
               <className>com.worklight.core.auth.ext.WebSphereLoginModule</className>
           </loginModule>
       </loginModules>

     • WASLTPARealm realm that uses the WASLTPAModule login module

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

       Note: You need to assign values to the login-page and error-page parameters in the realm definition, even though these parameters will not be used because DataPower will be responsible for sending the login form.
     • Security test (DataPowerTest in the following example) that uses the WASLTPARealm realm

       <securityTests>
           ...
           <customSecurityTest name="DataPowerTest">
               <test realm="wl_antiXSRFRealm" step="1"/>
               <test realm="WASLTPARealm" isInternalUserID="true" step="1"/>
           </customSecurityTest>
       <securityTests>

     For more information about the authentication-configuration file and the related security elements, see the following topics:

     • The authentication configuration file
     • MobileFirst security configuration
     • Implementing form-based authenticators
     • Configuring the MobileFirst LTPA realm
     • LTPA authenticator
     • WASLTPAModule login module
     • Security tests
• Protecting your resources Protect your selected resources (such as adapter procedures or your application) with the form-based LTPA security test that you created in Step 2 of the server configuration. See Security configurations of protected resources.
  For example, the provided sample MobileFirst project contains a JavaScript HTTP adapter with a simple getSecretData procedure (defined in DataPower/adapter/Protected-impl.js). This procedure is protected by the DataPowerTest security test that is defined in the sample project (see Step 2 of the server configuration). The procedure is protected by adding the securityTest attribute to the <procedure> element of the getSecretData procedure in the adapter descriptor file (DataPower/adapter/Protected.xml):

  <procedure name="getSecretData" securityTest="DataPowerTest"/>

• Configuring DataPower
  Configure your DataPower appliance with the sample MFP_LTPA_Integration configuration pattern.
  Note: The procedure was tested with DataPower Service Gateway XG45 version 7.0.0.10, and the included DataPower graphical user interface (GUI) references match this product version.
  1. Download the MFP_LTPA_Integration MobileFirst DataPower configuration pattern (MFP_LTPA_Integration.zip). The pattern is included in the MobileFirst LTPA DataPower integration package, and can also be downloaded directly here.
  2. Create a new application domain for your DataPower appliance.
  3. Configure the SSL proxy profile that will be used by DataPower to support HTTPS requests from the client application: The sample configuration pattern uses HTTPS (SSL) to communicate between the mobile device and the DataPower gateway. To support this communication, you need to define an SSL proxy profile. If you do not already have such a profile definition, define an SSL proxy profile in the DataPower WebGUI:
     Note: The SSL proxy profile is deprecated beginning with version 7.2.0 of IBM WebSphere DataPower. For information on how to migrate your DataPower configuration from an SSL proxy profile to an SSL client profile, see Migration from SSL Proxy Profile.
     1. In the search field of the navigation sidebar, search for SSL and select SSL Proxy Profile from the results list.
     2. In the profile configuration page, select Add.
     3. Enter the required configuration input for your profile. As part of the configuration you might need to upload an SSL certificate and private keys. The configuration of an SSL profile and the creation of a related certificate are outside the scope of the current documentation. For more information, see the IBM WebSphere DataPower documentation. You can see a sample configuration procedure that uses a self-signed CA root certificate in the following video: Protecting IBM MobileFirst Platform using DataPower.
        Note: Keep in mind that most mobile devices reject self-signed certificates. The workaround is outside the scope of the current documentation.
     4. Select Apply to apply your changes to the running configuration, and then select Save Configuration to save the changes to the startup configuration.
  4. Import the MFP_LTPA_Integration pattern:
     1. In the navigation bar of the DataPower WebGUI, select BluePrint Console, and make sure that you are logged in to the same application domain that you created in Step 2.
     2. Select the Patterns tab.
     3. Select the import graphic button (next to the New pattern button):
     4. In the Pattern file field of the Import pattern window, browse to the location of the MFP_LTPA_Integration.zip pattern archive file that you downloaded in Step 1. Then, select Import to import the pattern.
  5. Deploy the MFP_LTPA_Integration pattern to your DataPower appliance to create a service from the pattern:
     1. Select the Deploy button in the pattern heading line.
     2. In the Deploy pattern window, enter the required information for deploying the pattern and creating your service.
        • Service name is the service name that you want to display.
        • Description is an optional description of your service.
        • Step 2: Destinations configures the connection between the DataPower gateway and the MobileFirst Server back-end server:
          • URL is the full URL of your MobileFirst Server instance, of the format <http or https>://<host_name>:<port>/<project_name>.
          • SSL proxy profile is the name of the SSL profile that is used by your MobileFirst Server instance to communicate with the DataPower gateway. Configure this field only if your server uses SSL to communicate with the gateway.
        • Step 3: HTTPS connection configures the HTTPS (SSL) connection between the DataPower gateway and your client mobile application:
          • IP address is the IP address that is the entry point to your application. A value of 0.0.0.0 indicates that any IP address can be used.
          • Port is the port number for connecting to your application.
          • SSL proxy profile is the SSL proxy profile that you set up in Step 3. Select this profile from the list.
        • Step 4: Authenticate with LTPA and Step 5 configure the gateway's LTPA keys. Provide the same configuration input in both steps:
          Note: Due to a known issue in versions 7.2 and later of the DataPower firmware, the LTPA steps might not appear when you deploy the pattern. If this is the case, configure the LTPA key manually after your deploy the pattern.
          • LTPA key file is your application server's LTPA keys file: ltpa.keys (typically found in the <server_configuration_directory>/servers/worklight/resources/security directory of your MobileFirst Server).
          • Key file password is the password of the MobileFirst Server LTPA keys file. The default keys-file password for WebSphere is WebAS.
     3. Select Deploy pattern to deploy the pattern to your DataPower appliance and create the service.
     4. Verify that the pattern was deployed successfully: go to the Control Panel of the DataPower WebGUI, select Multi-Protocol Gateway, and verify that the gateway's Op-State value is up.
• Customization notes

  Edit the DataPower pattern and MobileFirst configurations, as needed, for your specific needs. Note the following points:

  Changing the authorized-users credentials or the authentication method of the DataPower AAA policy

  By default, the sample MFP_LTPA_Integration pattern checks the user credentials against a local:///MyAAA.xml file. The file path is hardcoded in the pattern's pattern/config/local/MyAAA.xml file, which also defines test credentials of several authorized users. To use the pattern, your server-configuration file must contain a <basicRegistry> element with one or more of the users that are configured in the pattern, as outlined in Step 1.d of the server configuration.

  You can modify the pattern's authorized-users credentials or authentication method, provided that you adjust the definition of the user-registry element in your server-configuration file to match the pattern. The default configuration is designed for testing during the development stage, and should be modified when connecting to an untrusted network or when moving from development to production. You can modify the configuration, for example, to integrate with an external user register or with any selected security system.

  To modify the authentication method, follow these steps in the DataPower WebGUI:

  1. In the search field of the navigation bar, search for AAA Policy. Select the MFPIntegrationWebHTTPSFormLTPAForm2LTPA policy from the displayed results.
  2. Select the Authentication tab. In the Method field, select your preferred authentication method. For example, you can choose Bind to LDAP server to bind against a lightweight directory access protocol (LDAP) server. Then, complete the required configuration for your selected method. The pattern can use any valid authentication method of the DataPower AAA policy, provided that the user identities that are returned by this method also exist in the application server's user registry.

  Configuring an HTTP (non-SSL) port

  The sample MFP_LTPA_Integration DataPower pattern is configured only for HTTPS (SSL) communication between the mobile device and the DataPower gateway. Therefore, you are required to configure an SSL proxy profile for this interface, as outlined in Step 3 of the DataPower configuration. However, during development, you can modify the DataPower configuration to open a non-SSL (HTTP) port:

  1. In the Control Panel of the DataPower WebGUI, select Multi-Protocol Gateway, and look for Front side settings.
  2. Add an HTTP Front side handler, choose a port for HTTP requests, and make sure to check GET in the list of allowed methods.

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. When using the sample DataPower MFP_LTPA_Integration pattern, the user credentials are passed as an LTPA token that is contained within a cookie, as demonstrated in the following initial-login, logout, and expired-authentication flow diagrams.

Figure 1. Initial-login flow

Figure 2. Logout flow

Figure 3. Expired-authentication flow