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
- 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
- Configuring your MobileFirst applications
- 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.
- Restart the MobileFirst Operations Console enterprise application.
- 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:
- Update your client mobile app.
- 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); });
- 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.
- 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>
- In your client mobile app, add the following JavaScript code to your HTML MobileFirst application:
- Define a multiprotocol gateway.
- In the IBM DataPower WebGUI, in the search box under Control Panel, enter Multi-Protocol and select New Multi-Protocol Gateway.
- 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:
- Policy worklight-basicauth for HTTP basic authentication. See Rules for HTTP basic authentication.
- Policy mpgw-form for HTML forms-based login authentication. See Rules for HTML forms-based authentication.
Backend URL Specify the address and port of the MobileFirst Server that is hosted on WebSphere Application Server.
- Create an AAA policy that supports the HTTP basic authentication
or HTML forms-based login policy that you defined in the previous
step.
- In the IBM DataPower WebGUI, in the search box under Control Panel, enter AAA, and then click Add.
- 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.
- For HTTP basic authentication, specify the settings as listed
in the following table.
- 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.
- DataPower configuration rules
Learn how to add the required authentication rules to your IBM WebSphere DataPower configuration.