API Connect

 View Only

Recipe: API Connect v5 Web Application Firewall (WAF)

By Will LIAO posted Mon September 27, 2021 05:05 PM


DataPower WAF configuration for the APIC Developer Portal

Originally published on May 25, 2017 / Updated on November 12, 2020

API Connect v5: Web Application Firewall (WAF)



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.



  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.


    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 and will be assigned to hostname apic.portal.


    The sample front side listener for the proxy will be, 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:


    The figure above outlines the hostname apic.portal is routed to IP (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 (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.


    • 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: 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.
    • 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.
    • 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).
    • 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

    3. Click on the Add Wizard.

      07.addWizard APIC_infraDoc - API Connect v5 WAF
    4. Give the WAF the name of your choice and click Next.

      08.WAFName APIC_infraDoc - API Connect v5 WAF
    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).



  4. Adding SSL Client Profile

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


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



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


    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.


    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.


    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.


    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.

  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.


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



  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.


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



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



    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.


    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.

  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.


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



    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.



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


    31. In the Configure Web Response Profile page, input the name 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.


    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.



    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.



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



    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.



    38. Click Commit and Done. Then Apply.

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


    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 or apic.portal, therefore I would replace the “YOUR_DATAPOWER_HOST_HERE” with 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 api-connect-web-application-firewall-waf/
  11. Completed

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



  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:


    If encountered please make the following adjustments:

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

    Handling 302 Redirects

    The following contains solution for 302 redirects within the WAF gateway.


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


    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:dpconfig="http://www.datapower.com/param/config" extension-element-prefixes="dp dpconfig"

    <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:reject>REDIRECTING</dp:reject -->