Overview

Skill Level: Intermediate

Assumptions: Implementer has exposure to IBM DataPower Gateways, basic understanding of RESTful operations, and basic networking knowledge.

This documentation details the creation of a Web Application Firewall service to proxy desired external URL requests to the APICv5 Developer Portal. The solution is for an on-prem APIC stack.

Ingredients

 

Step-by-step

  1. Summary

    NOTICE: It is strongly suggested that the proxy be built on a Multi-Protocol Gateway (MPGW) instead of this Web Application Firewall (WAF). You may use this tutorial to execute similar configurations for the MPGW. New tutorial publication TBA.

     

    The DataPower Web Application Firewall (WAF) is to reverse proxy the APIC Developer Portal as shown in the APIC infrastructure flow.

    APIC_infraDoc

    The sample configuration will showcase a proxy to the following APIC developer portal. Notice that our target resource (the dev portal IP) for the proxy will be 192.168.88.16 and will be assigned to hostname apic.portal.

     site

    The sample front side listener for the proxy will be 192.168.8.88, which is one of the DataPower network interfaces.

    In a live DMZ environment, hostnames will be required and the IP assigned to the host will be different from the external network zone opposed to the internal network zone:

     diagram

    The figure above outlines the hostname apic.portal is routed to IP 192.168.8.88 (DataPower interface) on the external network zone (this will not be the case in the configuration in this document), and the internal network zone hostname is routed to 192.168.88.16 (Dev Portal). Again, the reason being, is because the consumer browser will use the hostname “apic.portal” domain to reference relative files from the dev portal, rather than using the internal network address, which using the internal network address would fail. To clarify, the consumer will still be required to append the URI for the /organization and /catalog, because this is what gets appended to call the backend (Dev Portal).

    It is important to understand that the Dev Portal URL is required to remain the same between the front side and backside because the Dev Portal uses the HTTP Host Header as the domain to reference relative paths for different files and resources on the Dev Portal. The Dev Portal will use the URL defined in the APIM Portal Settings to send out activation emails also.

  2. Web Application Firewall (WAF) Configuration

    NOTICE: DO NOT configure the WAF proxy for the APIC dev portal on the APIC generated domain with DataPower. You will lose the configuration any time you need to “refresh” the gateway servers from APIC if you put this WAF in the APIC generated domain.

    Requirements:

    • If this is being created on your own system, ensure that your hostname (our sample hostname will be apic.portal) is routed to the dev portal IP (the sample used in this documentation will be IP: 192.168.88.16). You can assign the domain apic.portal to your ip in the etc/hosts/hosts file of your system for testing as shown in the figure below.

    03.etchosts

    • Ensure the same hostname to IP route is input in the static hosts of the DNS Settings. This is configured in the Default domain on DataPower.

    04.statichosts

    • Ensure that the developer portal URL is set to the hostname on APIC (this is set in the Settings of the catalog you’re using).

    05.portalURL

    • You’re required to have at least a sample self-signed crypto key/certificate. The purpose for this is for the front side listener to be configured with SSL. This is required for the dev portal’s basic authentication, otherwise, you will see that the login redirect will not work properly after the WAF is completed. Instructions on how to generate sample crypto files are in the Appendix under Generating Crypto Key and Cert on DataPower.
  3. Configuring the WAF with the Wizard

    1. Log into DataPower under the domain which you’ll be creating the WAF gateway. 

    2. Navigate to the WAF configuration
      06.waf_

    3. Click on the Add Wizard.
      07.addWizard

    4. Give the WAF the name of your choice and click Next.
      08.WAFName

    5. In the Back End (Server) Information screen page, enter in the Remote Host, port, and check the “Do you want to use SSL”. (Remember, the remote host will be the dev portal’s hostname similarly used in the APIM Portal Settings).
      09.completedWAF

  4. Adding SSL Client Profile

    6. Locate the SSL Client Profile and click on the (+) Add icon to add a new SSL Client Profile.
    10.ssladd

    7. Name the SSL Client Profile SSLClientProfile_AcceptAnyCert, select off for the Validate server certificate, and click on Apply.
    11.configSSLClientProfile

  5. Adding the Front End Listener

    8. Click Next when back in the Back End (Server) Information page. In the Front End (Client-Facing) Information page, enter the front side interface which the proxy will be listening on and check the SSL box. Our sample configuration will be 192.168.8.88 with port 443.

    NOTICE: You will need to use an interface which API Connect is not using if the port you use is 443.

    Once you click on Add the SSL Server Profile configuration will appear.
    12.FSH_

    NOTICE: Keep in mind, if you use any other port, ensure that the firewall will allow the port through the external network zone.

  6. Configuring SSL Server Profile

    9. In the SSL Server Profile section, click on the (+) Add icon.

    10. When the Configure SSL Server Profile window pops up, input the name, locate the Identification credentials, and click on the (+) Add icon.
    13.SSLServerProf

    11. When the Configure Crypto Identification Credentials window pops up, input the name and select mySampleCrypto (configured in Generating Crypto Keys and Certs on DataPower) for the Crypto Key and Certificate drop downs.
    14.mySampleCrypt
    After the configuration, continue to click on Apply until you are back in the original Create a Web Application Firewall Service window for the Front End (Client-Facing) Information.
    15.sslServerforWAF
    Accept the defaults from here on out:

    12. Click Next for the AAA Policy Information page.

    13. Click Next for the Shared Secret Key Information page.

    14. Click Next for the Request Information – Header and URL – encoded body page.

    15. Click Next for the Request Information – Query strings page.

    16. Click Next for the Request Information – Cookies page.

    17. Click Next for the Response Information page.

    18. Click Commit.

    16.commit

  7. Updating WAF: Advanced Configuration

    19. Once back in the Control Panel page, click on the WAF icon again to enter the WAF configuration and select the APIC_DevPortal_Proxy WAF. Click on the Advanced tab when inside the WAF configuration. Select off for the Normalize URI and Follow Redirects.
    17.WAFAdvanced

    20. Navigate back to the Main tab, locate the Application Security Policy section, and click on the (…) Edit icon.
    18.appsecpolicy

  8. Updating the Request Map

    21. Inside the Configure an Application Security Policy page, click on the Request Maps tab, and locate the Request Profile to click on the (…) Edit icon.
    19.reqmap

    22. In the Configure Web Request Profile page, click on the Methods & Versions tab, and ensure the following are selected from the figure below.
    20.crudselect

    23. Then click on the Threat Protection tab and uncheck the Filter Unicode, Filter Dot Dot, and Filter .exe.
    21.threatProtection

    24. Click on Apply.

  9. Updating the Response Map

    25. Back in the Configure an Application Security Policy page, click on the Response Maps tab and locate the Response Profile section to click on the (…) Edit icon.
    22.resmaps

    26. In the Configure Web Response Profile page, click on the Codes & Versions tab, and select codes for 400, 401, 404, 403, 408, and 500. (NOTE: You may also select all the codes, there are no issues with doing so.) Click Apply once complete.
    23.codesandversions

  10. Configure the handling of 302 Redirects in Response

    27 Back in the Configure an Application Security Policy page still under the Response Maps tab, locate the Matching Rule section, and click on the (+) Add icon.
    24.matchigres

    28. Name the Matching Rule RedirectMatch and click on Add.
    25.redirectmatch

    29. Drop down the Matching type to select HTTP, type in Location for the HTTP header, and type in * for the HTTP value match. Click on Apply when complete, then Apply in the proceeding page.
    26.resProfile

    30. Back in the Configure an Application Security Policy page, locate the Response Profile and click on the (+) Add icon.
    27.resProfile

    31. In the Configure Web Response Profile page, input the name RedirectAction.
    28.redirectaction

    32. Again, in the Codes & Versions tab, select codes for select codes for 400, 401, 404, 403, 408, and 500 as it was done in the previous step.

    33. Click on the Processing tab, locate the Non-XML Processing drop down, and select Side-Effect Rule. Then click on the (+) Add icon for the Non-XML Processing Rule.

    29.sideeffectrule

    34. Name the Processing Rule as RedirectProcessingRule, locate the Rule Direction drop down to select Server to Click, and click on the (+) Add icon for Rule Action.
    30.ruledirection

    35. Name the Processing Action RedirectLocationAction, ensure the Action Type is Transform with XSLT, type in NULL for Input, type in local:///ResetLocation.xsl for Transform File, and type in NULL for Output. Click Apply once completed.
    31.processingAction

    36. Click Apply again, and you should be back in the Configure Web Response Profile page with the following configurations set.
    32.completedresprofile

    37. Click Apply to get back into the Configure an Application Security Policy page. Click Add Response Map to add what was just created. Once added, move up the rule to the top as shown in the figure below.
    33.addresponsemap

    38. Click Commit and Done. Then Apply.

    39. Back in the main Control Panel page of DataPower, navigate to the File Management section.
    34.filemgmticon

    40. Upload the ResetLocation.xsl file into the local:/// directory. NOTICE: Ensure that you go into the file to update the code where YOUR_DATAPOWER_HOST_HERE is stated with the front side host you’re planning to use. For example, the aforementioned front side IP I’m using is 192.168.8.88 or apic.portal, therefore I would replace the “YOUR_DATAPOWER_HOST_HERE” with 192.168.8.88 or apic.portal. This forces the redirect of the requestors URL back to the front side URL. Reference: Handling 302 redirect error message in a Web
    Application Firewall.

    ResetLocation.xsl file

    35.resetlocfilemgmt

  11. Completed

    Once completed, you will be able to get to the Dev Portal site via DataPower’s front side.

    36.completed

  12. Extra Configurations

    Multipart-form-data body policy violated

    You may receive an error when a user attempts to register a new application on the dev portal where the WAF error message will display the following:

    37.multipartformdata

    If encountered please make the following adjustments:

    1. Navigate into your WAF service and edit the Application Security Policy:
      38.multipartwaf
    2. Once in the Configure an Application Security Policy window, local the Request Profile and edit the request policy:
      39.multipartreqprofile
    3. Once the Configure Web Request Profile pops up, click on the Multipart Form tab and update the Maximum Number of Parts to 20.
      40.multipartform
  13. Appendix

    Handling 302 Redirects

    The following contains solution for 302 redirects within the WAF gateway.
    http://www-01.ibm.com/support/docview.wss?uid=swg21318593

     

    Generating Crypto Key and Certs on DataPower

    As a quick sample creation of the crypto key and certs, the following is used to create the mySampleCrypt file to be used in the SSL Server Profile of the WAF or any front side handler.

    1. Navigate into the Crypto Tools section of the domain the WAF is being created in.
    2. Input
      1. mySampleCrypto for the Common Name (CN).
      2. 3650 for the Validity Period.
    3. Select on for the Export Private Key if you would like to export the key.
      41.cryptotool
    4. Click Generate Key to create the key and cert.

    You may export the sample crypto files in the temporary:/// directory of the File Management section.

    42.cryptolocation

    For more detailed information about generating crypto files may be found in the IBM knowledge center: https://www.ibm.com/support/knowledgecenter/SS9H2Y_7.5.0/com.ibm.dp.doc/cryptotool_generatingkeyscertificates.html

    ResetLocation.xsl code

     

    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
    xmlns:dp="http://www.datapower.com/extensions"
    xmlns:dpconfig="http://www.datapower.com/param/config" extension-element-prefixes="dp dpconfig"
    xmlns:dpquery="http://www.datapower.com/param/query"
    exclude-result-prefixes="soap">

    <xsl:param name="dpquery:URL"/>

    <xsl:template match="/">


    <xsl:variable name="LocationIn" select="dp:response-header('Location')"/>
    <xsl:variable name="lprotocol" select="substring-before(dp:variable('var://service/URL-in'), '//')"/>
    <xsl:variable name="luri" select="substring-after(substring-after($LocationIn, '//'), '/')"/>

    <!--
    <xsl:variable name="IpHostIn" select="substring-before(substring-after(dp:variable('var://service/URL-in'), '//'), '/')"/>
    -->
    <xsl:variable name="IpHostIn" select="concat('YOUR_DATAPOWER_HOST_HERE:', substring-after(substring-before(substring-after(dp:variable('var://service/URL-in'), '//'), '/'), ':'))"/>

    <xsl:variable name="newLocation" select="concat($lprotocol, '//', $IpHostIn, '/', $luri)"/>

    <!--dp:set-response-header name="'x-dp-response-code'" value="'301 redirected'"/-->
    <xsl:message>////////URL-in: [<xsl:value-of select="dp:variable('var://service/URL-in')"/>]</xsl:message>
    <xsl:message>////////Location-in: [<xsl:value-of select="$LocationIn"/>]</xsl:message>
    <xsl:message>////////new Location: [<xsl:value-of select="$newLocation"/>]</xsl:message>

    <dp:set-variable name="'var://context/gz/newloc'" value="$newLocation"/>

    <dp:set-response-header name="'x-dp-response-code'" value="'302 Moved Temporarily'"/>
    <dp:set-http-response-header name="'Location'" value="$newLocation"/>
    <!--
    <dp:set-response-header name="'x-dp-response-code'" value="'200 OK'"/>
    <dp:remove-http-response-header name="'Location'"/>
    -->
    <dp:freeze-headers/>
    <!-- dp:reject>REDIRECTING</dp:reject -->

    </xsl:template>


    </xsl:stylesheet>

17 comments on"API Connect v5: Web Application Firewall (WAF)"

  1. LauraMercauIBM September 02, 2017

    I can put SQL threat protection in this WAF?

  2. Thanks Will for this recipe. Very helpful.

  3. ajaykumarmaram January 23, 2018

    Hi wkliao,

    Thanks the tutorial. I’m facing once issue where I’m trying to implement the same. It was successfully created the firewall when I tried to login to the portal it is trowing back and error saying “You are not authorized to access this page.” can help me to resolve the issue.

    • @ajaykumarmaram
      I assume that this issue has been resolved, but you have to make sure that the uri and port number remain the same on the front end as the dev portal URL otherwise the resource locator for the login will be messed up, thus the credentials to login into dev portal will be lost (if the uri/port is different).

  4. Hi All,
    i have to suppress two values from response header and following the below code but it’s not working, getting 200 “Internal error”. Please suggest.

    • @Unacores
      Did you ever get around this? I’m not really sure what you’re trying to do here, maybe you can explain more?

  5. Hi All,
    i have to suppress two values from response header and following the below code but it’s not working, getting 200 “Internal error”. Please suggest.

  6. ajaykumarmaram May 11, 2018

    Hi Wkliao,
    I’ve created the web application proxy as described in this recipe. But when I try to load the portal all the files( like css) are referring from the original IP by default instead of taking it from the proxy IP or Host and when I try to login it is automatically redirecting to the original site. Can help he to resolve this issue. Thanks in Advance.

  7. Hi ajaykumarmaram – make sure you’re invoking the endpoint with the same port and uri as the portal URL… it needs to remain the same otherwise it’ll fail. Try with the same port and uri.

    • ajaykumarmaram May 11, 2018

      Ya Wkliao, I’m using same as default (443) and same URL (//).

      • RAVEENA07 May 21, 2018

        Hey, ajaykumarmaram
        i am facing the problem ….do you get the solution?? Are you able to login in developer portal??…if so please help me !!!

        • ajaykumarmaram May 23, 2018

          Able to login but after login it was redirecting to the original URL instead of proxy one.

          • @ajaykumarmaram, I’m not sure why it’s doing that, there may be a setting like the follow redirects which may not be set… I have recreate the problem and see. Are there any logs which hinted why this was happening?

  8. Hi Will, why the recommendation to use an MPGW, what are the advantages over the WAF?

    • Hi Guy,
      In general the mpgw has more flexibility and appears to be more closely managed by IBM over the years. For example, when web sockets were introduced to the gateways the fsh was able to support that where the waf couldn’t (not sure where that is today), but just an example I can remember. For APICs case, a WAF is enough, but I also suspect that the waf may be depricated due to datapower already having the xml firewall and the mpg which commonly does the same stuff.
      Hopefully that answers the question.

Join The Discussion