The IBM DataPower API gateway acts as a proxy between consumer applications and backend APIs. The API gateway secures, protects, and manages APIs by intercepting API requests and applying policies, such as throttling and security.

You can extend the gateway's functions to change the API flow by implementing custom gateway scripts and global policies in order to meet the requirements of your specific use case.

In order to integrate with the Cequence Unified API Protection (UAP) platform, the IBM DataPower API gateway must send all request and response data to a Cequence API Edge server. This process uses synchronously triggered custom scripts to process request and response data, then asynchronously format and post that data to the Cequence Bridge, which transmits the data to the Cequence Edge server. The Edge server analyzes the transaction data to provide actionable insights into your API traffic. Configuration of traffic filtering and sensitive data masking for the Cequence Bridge is discussed in a separate article.

Using the procedures in this article requires a bundle of files provided by Cequence. You can download this bundle from this page.

High level architecture

1. The client sends a request to the IBM DataPower API Gateway.
2. The request script intercepts the request and captures the request payload and metadata.
3. The request script forwards the request to the Backend/Target Applications.
4. The backend or target application generates a response, and any subsequent policies are executed.
5. The response script intercepts the response in order to capture the response payload and metadata.
6. The response script forwards the response to the clients or caller.
7. The script posts the combined request and response payload, along with the associated metadata, to the Cequence Bridge.
8. The Cequence Bridge forwards this information to the Cequence UAP Edge server for threat analysis, detection, and mitigation.

Integration setup

Setting up the Cequence UAP platform to integrate with the IBM DataPower API gateway is a multistep process.

• Create a Cequence policy
• Upload your TLS certificate
• Create a TLS client profile for Cequence
• Configure the TLS client profile for the gateway

Pre-Requisites

• IBM DataPower API gateway release 10.62 or later
• Cequence UAP platform release 7.3.X or later
• Client ID (Key) and Client Secret generated from the Cequence UAP platform UI
• Cequence Sensor Bridge deployed in close proximity to the IBM DataPower API Gateway
• Endpoints for the Cequence Bridge.

Generating a Client ID and Client Secret

Several Cequence components must authenticate to the Cequence UAP platform in order to transmit and receive data. Create authentication credentials in the Cequence UAP platform to enable this authentication.

1. Log in to the UAP management portal UI.
   The URL for the management portal is typically of the form https://ui.<your-tenant-name>.<domain>. Replace <your-tenant-name> with the name of your Cequence tenant organization. Replace <domain> with your domain name.
2. Select General Settings > User Management.
   The User Management pane appears.
3. Click the Clients tab.
4. Click Add New Client.
   The new client dialog box appears.
5. Type the client name in the Client Name field.
   This name is the client ID. Note the client ID for later use.
6. Enable the Traffic Ingestion toggle.
7. (Optional) To change the token lifespan from the default of 1800 seconds, type a whole number of seconds in Token Lifespan.
8. Click Save.
   A dialog box with the client secret appears.
9. Click the blue Copy icon to copy the secret to the clipboard, then click Close.
   The client is now set up. Note the client name for future use.
   The client list appears.
10. Note the value of the client secret for later use. This value will not be shown again later on the UI for security reasons.

Installing the integration

This procedure installs the software to integrate the Cequence UAP platform with the IBM DataPower API gateway. Other procedures later in this article configure the integration.

1. Download the archive file cequence-datapower-v1.zip from the Downloads page.
2. Copy the downloaded archive file to a directory named cequence. Create this folder if necessary.
   

   cp <$DOWNLOAD_DIR>/cequence-datapower-v1.zip $CEQUENCE_DP_HOME 
   mkdir -p $HOME/cequence && cd "$_"

3. Uncompress the archive file, then navigate to the cequence-datapower-v1 directory.
   The directory name may vary to match changes in the file name.
   

   unzip cequence-datapower-v1.zip 
   cd cequence-datapower-v1

4. Set the current directory as the value of the CEQUENCE_DP_HOME variable.

   export CEQUENCE_DP_HOME=$(pwd)

5. Copy the environment template to a new file.
   

   cd $CEQUENCE_DP_HOME 
   cp .env_example .env

6. Open the .env file in a text editor and set the value of the CEQUENCE_BRIDGE_URL variable to the URL of the Bridge endpoint.
7. Skip this step unless you require x-cequence performance headers that show latency. Set the value of the CEQUENCE_ENABLE_CUSTOM_RESPONSE_HEADERS variable to true.
8. Run the setup script.

   cd $CEQUENCE_DP_HOME/scripts 
   chmod +x *.sh 
   ./setup.sh

   The setup script generates the gateway scripts required for the Cequence Policy. The scripts are written to the $CEQUENCE_DP_HOME/generated folder 

The integration software is now installed. The directory structure and contents of the generated folder are as follows.

└── generated 
   ├── cequence-policy.zip 
   ├── cequence-tls-client-profile.zip 
   ├── cequence.crt 
   ├── cequence.js 
   └── postman-echo.crt 

Creating a Cequence Policy

You can create a policy for the Cequence UAP platform by importing a compressed file with the necessary items or  with manual configuration. The cequence-policy.zip file is generated by the setup script in the CEQUENCE_DP_HOME/generated/ directory.

Importing the compressed file

1. Log in to the IBM DataPower API gateway.
2. From the left sidebar, click Import, then select Import Configuration.
3. Click Choose file.
4. Select the cequence-policy.zip file and click Next.
5. Click Import.
6. Click Done. 

You can confirm successful file import by checking the Multi-protocol Gateway policy section of the Gateway Policy page for the new policy.

Manually configuring the policy

Skip this procedure if you have successfully imported the compressed file.

1. In the left sidebar, click File Management.
2. Only perform this step if the cequence directory does not exist. Click Actions > Create subdirectory.
3. In the Name field, type cequence, then click Confirm Create.
4. Click Continue.
5. Expand the local section.
6. Next to the cequence directory, click Actions > Upload Files.
7. Select the cequence.js file in the $CEQUENCE_DP_HOME/generated directory.
8. Click Upload.
9. Click Continue.
10. In the left sidebar, click Multi-Protocol Gateway Policy.
11. Click Add New Policy.
12. In the Name field, type cequence-policy, then click New Rule.
13. In the Name field, type cequence_rule, then double-click Match action of the rule.
14. Select __default-accept-service-providers__ from the dropdown, then click Done.
15. Drag a GatewayScript to the right of the Match rule.
    The GatewayScript icon is a set of braces, {}.
16. Double-click the GatewayScript.
17. From the dropdown, select INPUT.
18. Select local:///cequence, then select the uploaded script.
19. In the Output field, type CEQUENCE_SCRIPT_OUTPUT, then click Done.
20. Click Apply Policy.
    The IBM DataPower API Gateway automatically adds a Results Action to the end of the policy action queue.
21. At the right side of the queue, double-click the last Results Action.
22. From the dropdown, select INPUT, then Done.
23. Click Apply Policy.
24. Drag an Advanced action to the right of the GatewayScript action.
    The Advanced action icon is a black diamond with a white curved vertical line.
25. Double-click the Advanced action.
26. Select Set Variable, then click Next.
27. In the context field, type NULL.
28. In the Variable name field, type the following.

    context/CEQUENCE_BRIDGE_OUTPUT/_roottree

29. In the Variable value field, type the following.

    var://context/cequence/bridgePayload

30. Click Done.
31. Drag an Advanced action to the right of the Advanced action you configured previously.
32. Double-click the Advanced action.
33. Select Set Variable, then click Next.
34. In the context field, type NULL.
35. In the Variable name field, type the following.

    context/CEQUENCE_BRIDGE_OUTPUT/_extension/header/Content-Type

36. In the Variable value field, type the following.

    application/json

37. Click Done.
38. Drag an Advanced action to the right of the Advanced action you configured previously.
39. Double-click the Advanced action.
40. Select Conditional, then click Next.
41. From the Input drop-down, select CEQUENCE_SCRIPT_OUTPUT
42. In the Match Condition field, type the following.

    /cequence/processResultsAction/text() = 'true'

43. From the Action drop-down, select Results Asynchronous.
44. Click Create Action.
45. From the Input drop-down, select CEQUENCE_BRIDGE_OUTPUT.
46. From the Destination drop-down, select var://.
47. In the Destination field, type the following.

    context/cequence/bridgeUrl

48. Click Done.
49. In the Match Condition field, type the following.

    /cequence/processParseAction/text() = 'true'

50. From the Action drop-down, select Parse.
51. Click Create Action.
52. From the Input drop-down, select INPUT.
53. From the Output drop-down, select OUTPUT.
54. Click Done, then click Done again.
55. Click Apply Policy.
56. Click Save Config.
57. Click Close.

Uploading the Cequence security certificate

The IBM DataPower API gateway cannot import the Cequence TLS certificate from an archive file. This procedure uploads the security certificate.

If the settings of your existing TLS client profile's validation credentials are set to Disable Server Certificate Validation, you can skip this procedure and go directly to Configuring the Cequence Plugin.

 When you change the security certificate, perform this procedure again to add the new certificate. 

When the validation credential settings for your existing TLS profile are configured to check for dates, renew the Cequence certificate before expiry, then re-upload the certificate.

When you renew or update the Cequence Bridge security certificate, run the setup.sh script to generate a new cequence.crt file. Alternately, you can export the certificate from your browser.

1. In the left sidebar, click File Management.
2. Next to the certificate, click Actions, then Upload Files.
3. Choose the following file and click Upload.

   CEQUENCE_DP_HOME/generated/cequence.crt

4. If you are renewing or changing an existing certificate, click Overwrite Existing Files. Otherwise, skip this step.
5. Click Continue.
6. Click Save Config.
7. Click Close. 

Creating the Cequence TLS Client Profile

You can create a Cequence TLS client profile manually or by importing a compressed archive file.

Before you begin

Confirm that a valid Cequence security certificate is present.

Configure the TLS client profile by importing a compressed archive file

1. On the left sidebar, click Import Configuration.
2. Click Choose File.
3. Select the following file, then click Next.

   CEQUENCE_DP_HOME/generated/cequence-tls-client-profile.zip 

4. Click Import
5. Click Done

Display the list of TLS client profiles to confirm that the profile exists.

Manually configuring the TLS client profile

Skip this procedure if you have successfully configured a TLS client profile by importing a compressed archive file.

1. On the left sidebar, click TLS client profile.
2. Click Add.
3. In the Name field, type cequence-tls-client-profile.
4. Toggle Validate server certificate to off.
5. Click Apply.
6. Click Save Config.
7. Click Close.

Configuring the TLS client profile for the gateway

The asynchronous actions configured in the Cequence policy rule send payloads to Cequence over HTTPS. Using HTTPS requires a TLS client profile to establish secure connection.

Gateway APIs without an existing TLS client profile use HTTP. Configure these APIs to use the cequence-tls-client-profile configured previously.

Configuring existing TLS client profiles

This procedure is only necessary when an API is using an existing TLS profile with server certificate validation. This procedure adds the Cequence certificate to the existing validation credentials of the existing TLS profile.

1. In the IBM DataPower API gateway dashboard, navigate to the TLS profile in use.
2. Click Edit.
3. From the Certificates dropdown, select cequence-cert.
4. Click Add.
5. (Optional) To enable expired certificates, disable the Use CRL and Check Dates toggles.
6. Click Apply.
7. Click Apply.
8. Click Apply.
9. Click Save Config.
10. Click Close.

Configuring the Cequence plugin

When you use the default policy for your gateway, set the processing policy as cequence-policy. When you have an existing policy you want to use for the gateway, update the rules.

For example, a gateway with a default, non-custom policy appears similar to the following image.

 

By contrast, a gateway with an existing custom policy appears similar to the following image.

Replacing a default policy

These steps assume you are logged in to the IBM DataPower console.

1. Click Control Panel > Multi-Protocol Gateway.
2. Click the name of the gateway with the default policy you want to change.
3. From the dropdown, select cequence-policy.
4. Click Apply.

Repeat these steps for each multi-protocol gateway without an existing custom policy.

Modifying an existing custom policy

1. Click Control Panel > Multi-Protocol Gateway.
2. Click the name of the Gateway with the default policy you want to change.
3. Click the three-dot icon next to the existing processing policy.
   The configuration window appears.
4. When the policy has request and response rules, edit each rule. For each request rule, place the Cequence Processing rule at the start of the request rule, after the matching action. For each response rule, place the Cequence Processing rule at the end of the response rule. For each Both Directions rule, add the Cequence Processing rule at the start of the rule.
   These placements enable the capture of the request and response payloads as received by the Datapower gateway.
5. Double click Advanced.
6. Click Call Processing Rule, then click Next.
7. From the Input dropdown, select Input.
8. From the Processing rule dropdown, select cequence_rule.
9. From the Output dropdown, select NULL.
10. Click Done.
11. Click Apply.

Clearing a "PIPE Output not followed by PIPE Input" error

When the end of the response rule does not contain a default results action, you may see an error message similar to PIPE Output not followed by PIPE Input on action. To clear this error, set the output for the script before the Processing rule.

1. Click Control Panel > Multi-Protocol Gateway.
2. Click the name of the Gateway with the default policy you want to change.
3. Click the three-dot icon next to the existing processing policy.
   The configuration window appears.
4. Double click Advanced.
5. Double-click the double braces ({}) icon.
   The script editor pane appears.
6. From the Output dropdown, select OUTPUT.
7. Click Done.
   A new Default Results action appears at the end of the rule timeline.
8. Delete the new Default Results action.
9. Click Apply Policy, then close the popup.
10. Click Apply.

Testing the Plugin Setup

To test that the integration is operating correctly, first send some traffic through the system.

1. Log in to the Cequence UAP platform.
   The dashboard appears.
2. In the left hand navigation, in the Runtime Inventory section, click API Inventory.
   The API Inventory page appears in the Dashboard main area.
3. At the top of the API Inventory page, click the Active API Endpoints tab.
   Typically this is the active tab by default, so you may not need to perform this step.
4. At the top of the list of endpoints, click the vertical three-dot menu next to More.
   A list of other time frames appears.
5. Select 15 Min.
   The API Inventory displays API endpoints that have been active in the last 15 minutes.

Check the displayed results to confirm the traffic you sent appears in the inventory of active API endpoints.

Rolling back an integration

To roll back DataPower integration for APIs that did not have a previous custom policy, revert the policy to default.

1. Log in to the DataPower gateway.
2. Click Control Panel > Multi-Protocol Gateway.
3. Select the gateway to roll back.
4. Set the Processing Policy to default.
5. Click Apply.

Repeat for all applicable gateways.

For APIs that had an existing custom policy, delete the call processing rule for each rule in the policy.

1. Log in to the DataPower gateway.
2. Click Control Panel > Multi-Protocol Gateway.
3. Select the gateway to roll back.
4. Click the three-dot icon next to the existing processing policy.
   The configuration window appears.
5. Double click Advanced.
6. Double click the Call Processing Rule.
7. Click Delete.
8. Click Apply.

Rolling back the TLS client profile

When a gateway has an HTTP backend and uses the Cequence TLS profile, you can roll back the TLS profile.

1. Log in to the DataPower gateway.
2. Click Control Panel > Multi-Protocol Gateway.
3. Select the gateway to roll back.
4. Set the TLS client profile to none.
5. Click Apply.

Rolling back HTTPS backend gateways

For gateways with HTTPS backends that have had their validation credentials modified by adding the Cequence certificate, rolling back involves removing this certificate.

1. Log in to the DataPower gateway.
2. Click Control Panel > Multi-Protocol Gateway.
3. Select the gateway to roll back.
4. Click the three dots next to the validation credentials.
   The credential configuration window appears.
5. Click X next to the Cequence certificate.
6. Click Apply.
   The view returns to the credential profile.
7. Click Apply.
   The view returns to the gateway profile.
8. Click Apply.

Deleting the Cequence policy

1. Log in to the DataPower gateway.
2. Click Control Panel > Multi-Protocol Gateway Policy.
3. Click cequence-policy.
4. Click Delete Policy.

Deleting the Cequence TLS Client Profile

1. Log in to the DataPower gateway.
2. Search for the TLS client profile.
3. Select the TLS profile.
4. Click the Cequence profile.
5. Click Delete.

Deleting the Cequence validation credentials

1. Log in to the DataPower gateway.
2. Search for the Validation credentials.
3. Select the credentials.
4. Select cequence-creds.
5. Click Delete.

Delete the Cequence certificate

1. Log in to the DataPower gateway.
2. Search for the Cequence certificate.
3. Select the certificate.
4. Click cequence-cert.
5. Click Delete.

Removing the Cequence files

1. Log in to the DataPower gateway.
2. Search for file management.
3. Enter the file management page.
4. Select cequence.crt and cequence.js.
5. Delete the selected files.
6. Delete the cequence directory.