Integrating IBM WebSphere DataPower with a cluster of instances of MobileFirst Server

You can use IBM® WebSphere® DataPower® as a gateway for all incoming connections for IBM MobileFirst™ Platform Foundation and Application Center, and IBM HTTP Server (IHS) for load-balancing MobileFirst Server that are deployed on an IBM WebSphere Application Server 8.5 cluster or a Liberty profile server farm.

About this task

This procedure explains how to set up IBM MobileFirst Platform Foundation in the topology similar to the one shown in Figure 1.

Figure 1. IBM MobileFirst Platform Foundation integration with an IBM WebSphere Application Server 8.5 Cluster or a Liberty profile Server Farm

.

DataPower XI52 acts as the gateway for all IBM MobileFirst Platform Foundation and Application Center requests. DataPower validates all incoming user credentials against an LDAP registry. If the validation is successful, DataPower generates an LTPA token, which is present as part of a session cookie. This cookie is only valid for one session and is used for all further requests during that session. The cookies themselves contain information about the user that has been authenticated, the realm for which the user was authenticated (such as an LDAP server) and a timestamp. A request with a valid LTPA cookie can access a server that is a member of the same authentication domain as the first server. The request is automatically authenticated, thereby enabling single-sign-on (SSO).

All requests that reach the MobileFirst cluster or the backend application validate only the LTPA token. If the LTPA token is valid, the request is authenticated according to the rules that are set. The LTPA token guarantees that as long as the token is valid, all requests have SSO capability into all backend servers, including IBM MobileFirst Platform Foundation and Application Center.

The following sequence of events takes place when a mobile application makes a request (see Figure 2):

1. The mobile application makes a request to the DataPower gateway.
2. DataPower checks for an LTPA token in the incoming request.
3. If a valid LTPA token is present, the request is sent to the IBM MobileFirst Platform Foundation cluster.
   • If an LTPA token is not present or if the token is not valid, DataPower throws an authentication challenge. The mobile application handles the challenge and then prompts for user credentials.
4. The MobileFirst cluster validates the LTPA token and sends the request to the backend application server along with the LTPA token.
5. The backend application server validates the LTPA token and sends the response back to IBM MobileFirst Platform Foundation.
6. IBM MobileFirst Platform Foundation forwards the request to DataPower, and DataPower forwards it to the requesting mobile application.

Figure 2. Mobile application request-response flow

The Application Center request-response flow takes a similar route to the mobile application flow, except that requests are routed to the Application Center server instead of to the MobileFirst cluster (see Figure 3).

Figure 3. Application Center request-response flow

1. Configure server security.
   • On a WebSphere Application Server cluster:
     1. Login to the WebSphere Application Server integrated solutions console.
     2. Enable and configure application security.
        1. Navigate to Security > Global security, and then click Security Configuration Wizard.
        2. In the "Specify extent of protection" pane, select Enable application security.
        3. In the "Select user repository" pane, click Federated repositories to integrate with the LDAP server. Several different repositories, both LDAP and non-LDAP, can be configured in the federated repository. Enter the LDAP server details. Refer to the WebSphere Application Server documentation for detailed instructions.
        4. Complete the configuration steps and save your changes.
        5. On the "Global security" page, confirm that the following settings apply:
           • The Enable administrative security is selected.
           • The user account repository is set to LDAP.
     3. Enable WebSphere Application Server LTPA SSO between the MobileFirst Server cluster and backend servers. To support SSO across multiple WebSphere Application Server domains or cells, you must share the LTPA keys and the password among the domains. You need to export the LTPA keys from one of the domains and import them into all other domains in which you want to enable SSO. For detailed instructions, see Configuring LTPA and working with keys.
     4. Stop and restart the WebSphere Application Server cluster for the application security changes to take effect.
   • On a Liberty profile server farm:
     1. Integrate the LDAP server with Liberty profile, For detailed instructions, see Configuring LDAP user registries with the Liberty profile. You must configure LDAP user registries on each member of the liberty server farm. The following file is a sample LDAP configuration for Liberty server:

        <!-- LDAP configuration Start -->
        <ldapRegistry id="IBMDirectoryServerLDAP" realm="WASLTPARealm"
                      host="9.186.9.169" port="389" ignoreCase="true"
                      baseDN="dc=worklight,dc=com"
                      bindDN="cn=admin,dc=worklight,dc=com"
                      bindPassword="passw0rd"
                      ldapType="IBM Tivoli Directory Server">
        <idsFilters userFilter="(&amp;(uid=%v)(objectclass=posixAccount))"
                    groupFilter="(&amp;(cn=%v)(objectclass=posixGroup))"
                    userIdMap="*:uid"
                    groupIdMap="*:cn"
                    groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;groupOfNames:member;groupOfUniqueNames:uniqueMember" />
        </ldapRegistry>

     2. Configure SSO for the Liberty server farm. To enable SSO on Liberty, you must configure an LTPA key file for each Liberty server in the Liberty farm. See Configuring LTPA on the Liberty profile. The following file is a sample LTPA configuration for Liberty server:

        <ltpa keysFileName="${server.config.dir}/resources/security/ltpa.keystore" keysPassword="passw0rd" expiration="120" />

2. Configure MobileFirst Server.

   You can secure IBM MobileFirst Platform Foundation in a typical WebSphere Application Server runtime environment in two ways:

   Option 1

   Securing WebSphere Application Server using application security and securing the IBM MobileFirst Platform Foundation WAR file.

   Option 2

   Securing WebSphere Application Server using application security but not securing the IBM MobileFirst Platform Foundation WAR file.

   Option 1 provides greater authentication security. The application server, such as the IBM WebSphere Application Server Liberty profile (Liberty) protects all resources and forces users to log in before any other authentication mechanism. The behavior occurs regardless of the expected authentication order for a security test. See Supported configurations for LTPA for more information.

   Once the user has been successfully authenticated, an LTPA token is returned. This LTPA token needs to be present as part of all future requests from the mobile application, including adapter invocations. On the MobileFirst Server side, the call to the backend application should be modified to carry this LTPA token.

   For the purpose of explaining how this is done, assume that authentication configuration has a security test that uses a realm called WASLTPARealm, which is of type WebSphere LTPA. Assume also that there is an HTTP adapter defined on the server. Assume that the adapter is called SecureAdapter, and that it contains a procedure called getAccountInfo.

   The following code snippet shows how to pass the LTPA token when invoking an adapter procedure from the mobile application.

   function getAccountInfo(){ 
     var ltpaToken 
     if(WL.Client.isUserAuthenticated('WASLTPARealm')){ 
       var attrs = WL.Client.getUserInfo('WASLTPARealm', 'attributes'); 
       if(attrs){ 
         ltpaToken = attrs.LtpaToken; 
         console.log('Set ltpaToken again: '+ltpaToken); 
       } 
     } 
   
     var token = {'LtpaToken2' : ltpaToken}; 
     var invocationData = { 
       adapter: "SecureAdapter", 
       procedure: "getAccountInfo", 
       parameters: [token] 
     }; 
    
     WL.Client.invokeProcedure(invocationData, { 
       onSuccess: <on success callback>, 
       onFailure: <on failure callback> 
     }); 
   }

   On the server side, the adapter procedure needs to get the token, which is passed as a parameter. This parameter holds the LTPA token information that is used by the adapter to contact the backend service.

   function getAccountInfo(token) { 
     WL.Logger.info(token); 
   
     var input = { 
       method : 'get', 
       returnedContentType : 'xml', 
       cookies: token, 
       path : '<path to the backend service>' 
     }; 
   
     return WL.Server.invokeHttp(input); 
   }

   Since V6.2.0, MobileFirst Server is composed of one or more runtime environments, an administration console and administration services, an enterprise application store, and an operational analytics feature. MobileFirst Server components run as web applications on an application server. For more information about MobileFirst Server components, see Introduction to the MobileFirst Server components.

   The roles associated with the MobileFirst Operations Console and Administration Services components are different from the role defined in the WASLTPAModule login module (see WASLTPAModule login module). The MobileFirst Operations Console and Administration services roles should be mapped to the IT administrator users who are responsible for running administration tasks on the mobile application such as application deployment, management, version enforcement, and management of push notifications.

   The roles defined in the WASLTPAModule login module are part of the MobileFirst runtime environments. These roles should be mapped to the users or user groups that have been cleared to access the MobileFirst applications. MobileFirst Operations Console and Administration Services must be set up and configured before you proceed to deploy the MobileFirst runtime services See the following instructions depending on your application server, to map the administration user roles for MobileFirst Operations Console and Administration Services:

   • Configuring WebSphere Application Server full profile for MobileFirst Server administration
   • Configuring WebSphere Application Server Liberty profile for MobileFirst Server administration

   Once the runtime deployment is completed, you need to map the users against the roles defined in the WASLTPAModule login module or web.xml. In the WebSphere Application Server console, open the application configuration tab of the deployed MobileFirst Server and click Security role to user/group mapping to map the LDAP user to the MobileFirst roles.

   Figure 4. Mapping the LDAP user to WebSphere Application Server

   

   Select your role name and click Map users to map the LDAP user to this application.

   For IBM Worklight V6.0 and earlier, you must edit the web.xml file and add the user roles. For V6.1.0 and later, the roles can be added as part of the WASLTPAModule login module. See WASLTPAModule login module.

3. Configure Application Center.
   1. Complete the following configuration tasks depending on the server being used:
      • Configuring the Java EE security roles on WebSphere Application Server full profile
      • Configuring the Java EE security roles on WebSphere Application Server Liberty profile
   2. Manage users with LDAP.

      Application Center uses two security roles: appcenteradmin and appcenteruser. The LDAP users need to be mapped against the security roles.

      Depending on the server that you are using, refer to the "Configuring LDAP authentication" section under one of the following documentation links:

      • LDAP with WebSphere Application Server V7
      • LDAP with WebSphere Application Server V8.x
      • LDAP with Liberty profile
   3. Define the endpoint of the application resources.

      In this configuration, Application Center is behind DataPower, which is acting as a secure reverse proxy. To manage the applications on your device, the Application Center console must be able to locate the Application Center REST services and generate the required number of URI that enable the mobile client to find the Application Center REST services.

      By default, the URI protocol, host name, and port are the same as those defined in the web application server used to access the Application Center console; the context root of the Application Center REST services is applicationcenter. When the context root of the Application Center REST services is changed or when the internal URI of the web application server is different from the external URI that can be used by the mobile client, the externally accessible endpoint (protocol, host name, and port) of the application resources must be defined by configuring the web application server. (Reasons for separating internal and external URI could be, for example, a firewall or a secured reverse proxy that uses HTTP redirection.)

      The following Application Center JNDI properties must reference the DataPower gateway's details:

      • ibm.appcenter.services.endpoint
      • ibm.appcenter.proxy.protocol
      • ibm.appcenter.proxy.host
      • ibm.appcenter.proxy.port

      Depending on the server type, set the Application Center JNDI properties by completing one of the following procedures:

      • Configuring the endpoint of application resources (full profile)
      • Configuring the endpoint of the application resources (Liberty profile)
4. Configure DataPower. DataPower XI52 acts as the gateway for all IBM MobileFirst Platform Foundation and Application Center requests. DataPower validates all incoming user credentials against an LDAP registry. The following sections show how to configure DataPower.
   1. Create a new multi-protocol gateway. Complete the following steps:
      1. From the DataPower XI52 control panel, click the Multi-Protocol Gateway icon to open the Multi-Protocol Gateway main page.
         Figure 5. Accessing the Multi-Protocol Gateway main page

         
      2. Click Add to add a new gateway.
      3. Provide a name for the gateway and set Type to dynamic-backend.
      4. Make sure that Request Type and Response Type are set to Non-XML.
      5. On the Advanced tab page, select Follow Redirects and Process Backend Errors.
      6. On the Stylesheet Params tab page, add the parameters listed in Table 1:

         Table 1. Stylesheet parameters

         Parameter name	Value
         {http://www.datapower.com/param/config}applicationcenterBackend	http://<appcenterHostName>:<port>
         {http://www.datapower.com/param/config}worklightBackend	http://<worklightIHSHostName>:<port>

      7. On the General tab page, add an HTTPS (SSL) Front Side Handler with reverse SSL Proxy profile. Ensure that the following methods and versions are selected:
         • HTTP 1.0
         • HTTP 1.1
         • POST method
         • GET method
         • PUT method
         • HEAD method
         • OPTIONS
         • DELETE method
         • URL with Query Strings
         • URL with Fragment Identifiers
      8. Click the plus sign (+) to add a new multi-protocol gateway policy.
      9. Provide a name for the policy, click Apply Policy, and then click Close Window. The policy is added to the gateway.
      10. Apply your configuration.
   2. Edit the multi-protocol gateway policy. Add the following rules to provide form-based authentication, generate an LTPA token and verify the LTPA token. All the rules are described in the following tables. You must list them in the same order.
      1. worklight-ssl-policy_skipFavicon: see Table 2
      2. worklight-ssl-policy_verifyLTPA: see Table 3
      3. worklight-ssl-policy_allowSSLLoginPage: see Table 4
      4. worklight-ssl-policy_worklightSSLLogin: see Table 5

      Table 2. Properties of worklight-ssl-policy_skipFavicon

      Property	Value
      Direction	Client to Server.
      Match	Type = URL Pattern = /favicon.ico
      Advanced	"Set Variable" -> var://service/mpgw/skip-backside = 1
      Result	Not applicable.

      Table 3. Properties of worklight-ssl-policy_verifyLTPA

      Property	Value
      Direction	Client to Server.
      Match	Type = HTTP HTTP tag = Cookie Pattern = *LtpaToken*
      AAA	Input: INPUT Output: NULL Add a new AAA Policy named VerifyLTPA with the following configuration: Extract Identity: LTPA token Method: Accept LTPA Token. Acceptable LTPA versions: WebSphere version 1 and WebSphere version 2 LTPA key file: upload the LTPA keyfile. LTPA key file password: specify the password for the LTPA keyfile. Extract Resource: URL Sent by Client Authorization: Allow any authenticated client.
      Transform	Upload route.xsl. See Sample dynamic routing stylesheet. Input: INPUT Output: auth
      Result	Not applicable.

      Table 4. Properties of worklight-ssl-policy_allowSSLLoginPage

      Property	Value
      Direction	Client to Server.
      Match	Type = URL Pattern = /(Login|Error)Page\.htm(l)?(\?originalUrl=.*)?
      AAA	Input: INPUT Output: NULL Add a new AAA Policy named AllowSSLLoginPage with the following configuration: Method: HTML Form-based Authentication HTML Form Policy: Create one with the default values, but edit these values: Use SSL For Login: enabled SSL Port: port on which the multi-protocol gateway is listening. Authentication: Pass identity token to authorization phase Resource extraction: URL sent by client Authorization: Always allow
      Result	Not applicable.

      Table 5. Properties of worklight-ssl-policy_worklightSSLLogin

      Property	Value
      Direction	Client to Server.
      Match	Boolean Or Combinations: On Type = URL Pattern: /worklightconsole/* Type = URL Pattern: /wladmin/* Type = URL Pattern: /worklight/* Type = URL Pattern: /j_security_check Type = URL Pattern: /applicationcenter/* Type = URL Pattern: /appcenterconsole/*
      Advanced	Convert Query Params to XML Action
      AAA	Create a new AAA Policy named worklightSSLFormLogin with the following configuration: Extract Identity: Method: HTML Form-based Authentication HTML Form Policy: Select the same policy created in the previous step. Authentication: Method: Bind to LDAP server Enter the HostName, Port(636) Create an SSL Forward proxy profile with the LDAP server's SSL certificate. LDAP Bind DN, in this case would be: cn=admin,dc=worklight,dc=com Enter the LDAP Bind Password. LDAP Prefix : uid= LDAP Suffix : ou=people,dc=worklight,dc=com Resource extraction: URL sent by client Authorization: Allow any authenticated client. Post Processing: Generate LTPA Token -> on. LTPA Token Version: WebSphere version 2 LTPA Key File: Select the LTPA keys file LTPA key file password: Specify the password for the LTPA keys file.
      Transform	Upload route.xsl file. See Sample dynamic routing stylesheet. Input: INPUT Output: auto
      Result	Not applicable.