The WSO2 API Manager includes a gateway that acts as a proxy between consumer applications and backend APIs. In addition to acting as a proxy, the gateway secures, protects, and manages APIs by intercepting requests and applying policies such as throttling and security controls. You can extend the gateway's functions with a custom handler to meet specific requirements and use cases.

This article describes how to integrate WSO2 API Manager with the Cequence Platform to discover and protect the APIs that WSO2 API Manager manages, and is intended for administrators who install and configure the integration.

To integrate with the Cequence Platform, WSO2 API Manager uses a custom mediator that installs as a plugin. The mediator extends the AbstractHandler class. WSO2 triggers the mediator asynchronously to process request and response data, then formats the data as JSON for the Cequence Platform. The mediator sends each formatted transaction to the Cequence Common Library, which batches transactions and sends them to Cequence Bridge.

Cequence Edge then processes the transactions and provides insight into your API traffic.

High-level architecture

The following steps describe the API call flow between WSO2 API Manager and the Cequence Platform.

1. When a client sends a request to a backend service, the request first passes through WSO2 API Manager. The Cequence policy intercepts the request and captures its payload and metadata.
2. The Cequence plugin collects the API request metadata.
3. WSO2 API Manager forwards the request to the backend service for processing.
4. When the response arrives from the backend service, WSO2 API Manager intercepts the response and captures its payload and metadata.
5. The Cequence plugin collects the API response metadata.
6. WSO2 API Manager sends the response to the client.
7. WSO2 API Manager posts the request and response payloads and metadata to Cequence Bridge, which forwards them to Cequence Edge for threat analysis, detection, and mitigation.
8. The Cequence plugin formats, batches, and asynchronously sends the request and response payload and metadata as JSON transactions to the Cequence Platform.

Prerequisites

Verify that the following prerequisites are in place before you begin the installation procedures.

• WSO2 API Manager 4.5.0
• Java 17
• The Cequence plugin bundle for WSO2 API Manager, provided by the Cequence team
• curl
• Python 3.x
• A client ID and client secret generated from the Cequence Platform UI
• For Kubernetes, OpenShift, or ROSA deployments, kubectl or oc access to the target cluster

Detailed prerequisites setup

The following procedure establishes the client ID and client secret required for the remaining steps.

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

The client ID and client secret are now available for authenticating Cequence components to the Cequence Platform.

Installing the Cequence passive plugin

Complete the following tasks in sequence to install the Cequence passive plugin for WSO2 API Manager.

Downloading and extracting the plugin archive

Complete the following steps to download the plugin archive and extract it into your working directory.

1. Download the Cequence plugin bundle for WSO2 API Manager.

2. Extract the archive.

   tar -xvf cequence-wso2-package.tar.gz

The plugin files are now available for configuration and deployment.

To install the Cequence passive plugin, use one of the following methods.

• Automation utility (recommended).
• Manual installation.

Using the automation utility

Complete the following tasks in order to install the plugin using the automation scripts.

Preparing the environment file

From the plugin bundle directory, copy the example environment file to a new .env file.

cd cequence-wso2-package
cp .env.example .env

The following table describes the environment variables used to configure the plugin.

The following excerpt shows a sample .env file.

CEQUENCE_AUTH_ENDPOINT=https://auth.<cequence subdomain>/auth/realms/cequence/protocol/openid-connect/token
CEQUENCE_EDGE_ENDPOINT=https://edge.<cequence subdomain>/api-transactions
CEQUENCE_CLIENT_ID=<cequence client ID>
CEQUENCE_CLIENT_SECRET=<cequence client secret>
CEQUENCE_COMMON_LIB_LOG_LEVEL=INFO

WSO2_APIM_HOME=/home/wso2carbon/wso2am-4.5.0

BUNDLE_PATH=./bundle/cequence_wso2_overlay

PLATFORM=docker

# host only
SSH_HOST=
SSH_USER=ubuntu
SSH_KEY_PATH=

# docker only
DOCKER_CONTAINER=wso2am
DOCKER_HOST=

# k8s, OpenShift, ROSA, or EKS only
K8S_NAMESPACE=wso2-apim
K8S_POD=
KUBECONFIG_PATH=
KUBECTL_BIN=kubectl
K8S_LOG4J2_CONFIGMAP=

Installing prerequisites

Run the following command to install any missing prerequisites. When the required libraries are already installed, the script leaves them unchanged.

./init.sh

Deploying the plugin

From the plugin bundle directory, run the following command to deploy the Cequence plugin to the platform configured in the .env file.

./deploy.sh

Monitor the output for errors. When the script finishes running, verify that the output confirms the deployment completed successfully.

Uninstalling the plugin

From the plugin bundle directory, run the following command to remove the Cequence plugin from the target platform.

./destroy.sh

Monitor the output for errors. When the script finishes running, verify that the output confirms the removal completed successfully.

Performing a manual installation

Manual installation differs by platform. Complete the steps for your platform.

Installing manually on a host or EC2 instance

When your host is remote, run the same commands over SSH, or copy the files to the host first and run the remaining commands in an SSH session.

Complete the following steps on the host where WSO2 API Manager is installed.

1. Set the $WSO2_APIM_HOME and $BUNDLE environment variables to the WSO2 installation path and the plugin bundle location.

   export WSO2_APIM_HOME=/home/wso2carbon/wso2am-4.5.0   # adjust to your install path
   export BUNDLE=scripts/bundle/cequence_wso2_overlay      # from this repo, wherever you cloned it

2. Copy the plugin JAR files into the WSO2 installation.

   cp "$BUNDLE"/repository/components/lib/*.jar "$WSO2_APIM_HOME/repository/components/lib/"

3. Back up and replace the API template files with the Cequence-provided templates.

   for f in "$BUNDLE"/repository/resources/api_templates/*.xml; do
     name=$(basename "$f")
     target="$WSO2_APIM_HOME/repository/resources/api_templates/$name"
     cp "$target" "$target.original.bak"
     cp "$f" "$target"
   done

4. Back up and replace the log4j2.properties file with the Cequence-provided version.

   cp "$WSO2_APIM_HOME/repository/conf/log4j2.properties" "$WSO2_APIM_HOME/repository/conf/log4j2.properties.original.bak"
   cp "$BUNDLE/repository/conf/log4j2.properties" "$WSO2_APIM_HOME/repository/conf/log4j2.properties"

5. Create the cequence.properties file with your Cequence connection values.

   cat > "$WSO2_APIM_HOME/repository/conf/cequence.properties" <<EOF
   authEndpointUrl=<cequence auth endpoint>
   transactionEndpointUrl=<cequence edge endpoint>
   clientId=<cequence client ID>
   clientSecret=<cequence client secret>
   commonLibLogLevel=INFO
   EOF

6. Restart the WSO2 API Manager.

   # Restart
   if ps aux | grep -v grep | grep -q wso2server.sh; then
     "$WSO2_APIM_HOME/bin/wso2server.sh" restart
   else
     "$WSO2_APIM_HOME/bin/wso2server.sh" start
   fi

7. Tail the WSO2 log file and verify that Cequence log entries appear.

   export WSO2_APIM_HOME=/home/wso2carbon/wso2am-4.5.0   # adjust to your install path
   tail -f "$WSO2_APIM_HOME/repository/logs/wso2carbon.log" | grep -i cequence

The WSO2 API Manager is now sending traffic data to the Cequence Platform.

Installing manually on Docker

Complete the following steps on the host running the WSO2 API Manager Docker container.

1. Set the $CONTAINER, $BUNDLE, and $APIM_HOME environment variables for your Docker container.

   export CONTAINER=wso2am
   export BUNDLE=scripts/bundle/cequence_wso2_overlay
   export APIM_HOME=/home/wso2carbon/wso2am-4.5.0   # path inside the container

2. Copy the plugin JAR files into the container.

   for jar in "$BUNDLE"/repository/components/lib/*.jar; do
     docker cp "$jar" "$CONTAINER:$APIM_HOME/repository/components/lib/$(basename "$jar")"
   done

3. Back up and replace the API template files inside the container with the Cequence-provided templates.

   for f in "$BUNDLE"/repository/resources/api_templates/*.xml; do
     name=$(basename "$f")
     target="$APIM_HOME/repository/resources/api_templates/$name"
     docker exec "$CONTAINER" cp "$target" "$target.original.bak"
     docker cp "$f" "$CONTAINER:$target"
   done

4. Back up and replace the log4j2.properties file inside the container with the Cequence-provided version.

   docker exec "$CONTAINER" cp "$APIM_HOME/repository/conf/log4j2.properties" "$APIM_HOME/repository/conf/log4j2.properties.original.bak"
   docker cp "$BUNDLE/repository/conf/log4j2.properties" "$CONTAINER:$APIM_HOME/repository/conf/log4j2.properties"

5. Create the cequence.properties file with your Cequence connection values, then copy it into the container.

   Set the file's permissions to 644 before copying it. A file created with default permissions might not be readable by the container's WSO2 process, which prevents the plugin from reading its configuration.

   cat > /tmp/cequence.properties <<EOF
   authEndpointUrl=<cequence auth endpoint>
   transactionEndpointUrl=<cequence edge endpoint>
   clientId=<cequence client ID>
   clientSecret=<cequence client secret>
   commonLibLogLevel=INFO
   EOF
   chmod 644 /tmp/cequence.properties
   docker cp /tmp/cequence.properties "$CONTAINER:$APIM_HOME/repository/conf/cequence.properties"
   rm -f /tmp/cequence.properties

6. Restart the container.

   docker restart "$CONTAINER"

7. Tail the WSO2 log file inside the container and verify that Cequence log entries appear.

   export CONTAINER=wso2am
   export APIM_HOME=/home/wso2carbon/wso2am-4.5.0   # path inside the container
   docker exec "$CONTAINER" tail -f "$APIM_HOME/repository/logs/wso2carbon.log" | grep -i cequence

The Cequence plugin is now installed in the container and WSO2 API Manager is sending traffic data to the Cequence Platform.

Installing manually on Kubernetes, OpenShift, or EKS

Use oc on OpenShift or ROSA, or kubectl on EKS. The commands are otherwise identical, so replace the binary name as needed.

Complete the following steps against the cluster running WSO2 API Manager.

1. Set the environment variables for your cluster, then identify the target pod.

   export NAMESPACE=wso2-apim
   export BUNDLE=scripts/bundle/cequence_wso2_overlay
   export APIM_HOME=/home/wso2carbon/wso2am-4.5.0   # path inside the pod
   POD=$(kubectl get pods -n "$NAMESPACE" -o jsonpath='{.items[0].metadata.name}')
   echo "Target pod: $POD"

2. Copy the plugin JAR files into the pod.

   for jar in "$BUNDLE"/repository/components/lib/*.jar; do
     kubectl cp -n "$NAMESPACE" "$jar" "$POD:$APIM_HOME/repository/components/lib/$(basename "$jar")"
   done

3. Back up and replace the API template files inside the pod with the Cequence-provided templates.

   for f in "$BUNDLE"/repository/resources/api_templates/*.xml; do
     name=$(basename "$f")
     target="$APIM_HOME/repository/resources/api_templates/$name"
     kubectl exec -n "$NAMESPACE" "$POD" -- cp "$target" "$target.original.bak"
     kubectl cp -n "$NAMESPACE" "$f" "$POD:$target"
   done

4. Back up and replace the log4j2.properties file inside the pod with the Cequence-provided version.

   kubectl exec -n "$NAMESPACE" "$POD" -- cp "$APIM_HOME/repository/conf/log4j2.properties" "$APIM_HOME/repository/conf/log4j2.properties.original.bak"
   kubectl cp -n "$NAMESPACE" "$BUNDLE/repository/conf/log4j2.properties" "$POD:$APIM_HOME/repository/conf/log4j2.properties"

5. Create the cequence.properties file with your Cequence connection values, then copy it into the pod.

   Set the file's permissions to 644 before copying it, for the same reason described in the Docker steps.

   cat > /tmp/cequence.properties <<EOF
   authEndpointUrl=<cequence auth endpoint>
   transactionEndpointUrl=<cequence edge endpoint>
   clientId=<cequence client ID>
   clientSecret=<cequence client secret>
   commonLibLogLevel=INFO
   EOF
   chmod 644 /tmp/cequence.properties
   kubectl cp -n "$NAMESPACE" /tmp/cequence.properties "$POD:$APIM_HOME/repository/conf/cequence.properties"
   rm -f /tmp/cequence.properties

6. Restart the pod by deleting it. Kubernetes automatically recreates the pod from its deployment.

   kubectl delete pod -n "$NAMESPACE" "$POD"

7. Wait for the new pod to reach the Ready state.

   kubectl get pods -n "$NAMESPACE" --watch

8. Tail the WSO2 log file inside the new pod and verify that Cequence log entries appear.

   export NAMESPACE=wso2-apim
   export APIM_HOME=/home/wso2carbon/wso2am-4.5.0   # path inside the pod
   POD=$(kubectl get pods -n "$NAMESPACE" -o jsonpath='{.items[0].metadata.name}')
   kubectl exec -n "$NAMESPACE" "$POD" -- tail -f "$APIM_HOME/repository/logs/wso2carbon.log" | grep -i cequence

The Cequence plugin is now installed in the pod and WSO2 API Manager is sending traffic data to the Cequence Platform.

Troubleshooting

The following issues are commonly encountered during and after installation.

• No Cequence log lines appear, even with real traffic. Verify that the handler is registered in the specific api_templates/*.xml file used to generate the API you are testing. Run grep -c com.cequence.logging.LoggingApplication against that file. A plain HTTP API created through the Publisher REST API uses default_api_template.xml, not velocity_template.xml. Patching only velocity_template.xml leaves REST-API-created endpoints without Cequence instrumentation.
• The handler does not appear to run on one specific API, even though the templates are patched correctly. Check whether that API's generated synapse artifact registers the handler twice. WSO2 drops the entire handler chain for an API when the same handler class appears twice in its configuration. This can happen because some templates, including velocity_template.xml, contain the <handlers> tag in two places. Patch only the first occurrence.
• cequence.properties is unreadable, or the plugin never initializes (Docker or Kubernetes only). Check the file's permissions inside the container or pod. A file staged locally with mktemp or a similar command defaults to permission mode 600, and both docker cp and kubectl cp preserve that mode during the copy. Run chmod 644 on the file before copying it.
• A previously working installation stops working after a routine restart (Kubernetes only). Deleting a pod discards any state that is not persisted elsewhere. Check whether your Helm chart mounts a ConfigMap over log4j2.properties, and verify that $WSO2_APIM_HOME is backed by a PersistentVolume.
• WSO2 Carbon started never appears in the log. This message is the startup marker for WSO2 4.5.0. Do not wait for WSO2 API Manager started, which was the startup message in WSO2 2.6.0 and does not appear in 4.5.0 logs.