This article describes how to integrate Apigee Hybrid with the Cequence Platform in passive mode over HTTPS. The article is for Apigee administrators who install and configure the Cequence integration.

How the integration works

An Apigee shared flow is a bundle of policies and resources, such as scripts, that several Apigee API proxies can reuse. In passive mode, the Cequence integration uses shared flows to copy request and response data from your API traffic.

The Cequence shared flows extract the data from each request and response, read the key fields, and send the data to Cequence Bridge. Cequence Bridge forwards the data to the API Edge traffic ingestion endpoint of the Cequence Platform. The Cequence Platform analyzes the data independently of your API traffic.

The following list describes how data moves through the integration.

1. A client sends a request to an API proxy in Apigee. The cequence-pre-proxy-sharedflow shared flow intercepts the request and captures the request payload and metadata.
2. Apigee processes the request and forwards the request to the backend application.
3. The backend application sends a response. The cequence-post-proxy-sharedflow shared flow intercepts the response and captures the response payload and metadata.
4. The post-proxy shared flow sends the request and response data to Cequence Bridge. Cequence Bridge forwards the data to the Cequence Platform API Edge for threat analysis, detection, and mitigation.
5. Cequence Bridge returns a success response. When the call to Cequence Bridge fails, the integration ignores the error, and the API traffic continues without interruption.
6. Apigee returns the backend response to the client.

Limitations

The passive integration with Apigee Hybrid has the following limitations.

• When a request body or response body is larger than 32 kibibytes (32,768 bytes), the integration truncates the body to 32,768 bytes. The integration adds the header cq-body-truncated=true to the data that the Cequence Platform receives.
• The integration supports only Cequence Bridge configurations that do not require authentication.
• The integration sends data to Cequence Bridge over HTTPS only.

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

Before you install the integration

Verify that your environment meets the following requirements before you install the integration.

Access to the following command-line tools.

You are logged in to the Google Cloud CLI. To log in, run the gcloud auth login command.

A Google Cloud account with the Apigee Admin role and access to your Apigee organization.

A Cequence Bridge endpoint that Apigee can reach over HTTPS.

You have downloaded the Cequence Apigee Hybrid integration bundle from the Cequence help center.

Installation methods

You can install the integration using the cq-cli utility or using manual steps in the Apigee UI. Cequence recommends the cq-cli utility. The cq-cli utility deploys the shared flows, attaches the shared flows to the flow hooks of your environment, and applies the settings from an environment file.

The manual method also uses the cq-cli utility and an environment file. In the manual method, you build the shared flow bundles on your workstation, and then upload, deploy, and attach the shared flows yourself in the Apigee UI.

Installing the integration using the cq-cli utility

Use this procedure to install the integration from a terminal on your workstation. Start this procedure in the directory where you downloaded the Cequence integration bundle.

1. From the bundle, find the archive for your operating system and processor architecture. The bundle contains the following archives.

   platform-zips
      ├── cequence-apigee-hybrid-plugin-darwin-amd64.tar.gz
      ├── cequence-apigee-hybrid-plugin-darwin-arm64.tar.gz
      ├── cequence-apigee-hybrid-plugin-linux-amd64.tar.gz
      ├── cequence-apigee-hybrid-plugin-linux-arm64.tar.gz
      ├── cequence-apigee-hybrid-plugin-windows-amd64.tar.gz
      └── cequence-apigee-hybrid-plugin-windows-arm64.tar.gz

2. From the terminal, extract the archive.

   tar -xvf <archive name>

   The archive extracts to a directory with the following structure. This example shows the archive for macOS on ARM processors.

   cequence-apigee-hybrid-plugin-darwin-arm64
   └── cequence-apigee-hybrid-plugin
       ├── .env.example
       ├── cequence-apigee-hybrid-plugin.tar.gz
       ├── cq-cli
       └── README.md

3. From the terminal, change to the cequence-apigee-hybrid-plugin directory that contains the cq-cli utility.

4. Make the cq-cli utility executable.

   chmod +x cq-cli

5. (Optional) To view the operations that the cq-cli utility supports for Apigee, run the following command.

   ./cq-cli apigee

   The terminal displays the following output.

   Manage apigee
   Usage:
     cq-cli apigee [command]
   Available Commands:
     collect-logs      Collect logs for apigee
     deploy            Deploy apigee
     destroy           Destroy all apigee resources
     init              Initializing CLI for apigee deployment
     upgrade           Upgrade apigee template
     verify-deployment Verify apigee deployment
   Flags:
     -h, --help   help for apigee
   Use "cq-cli apigee [command] --help" for more information about a command.

6. Create an environment file from the example file.

   cp .env.example .env

7. In a text editor, open the .env file and set the values for your environment. For a description of each setting, see Environment file settings in this article.

8. Initialize the cq-cli utility. The init command extracts the integration files, sets up the configuration, and validates your environment before deployment.

   ./cq-cli apigee init --tar ./cequence-apigee-hybrid-plugin.tar.gz

9. Deploy the integration.

   ./cq-cli apigee deploy

   The terminal displays output similar to the following example. The READY status shows that Apigee deployed each shared flow. The flowHookPoint entries show that the cq-cli utility attached each shared flow to a flow hook.

   Sharedflow deployment completed with status:  READY
   attaching cequence-pre-proxy-sharedflow at PreProxyFlowHook ...
   {
       "flowHookPoint": "PreProxyFlowHook",
       "sharedFlow": "cequence-pre-proxy-sharedflow",
       "continueOnError": true
   }
   ...
   Sharedflow deployment completed with status:  READY
   attaching cequence-post-proxy-sharedflow at PostProxyFlowHook ...
   {
       "flowHookPoint": "PostProxyFlowHook",
       "sharedFlow": "cequence-post-proxy-sharedflow",
       "continueOnError": true
   }

The Cequence shared flows are now deployed in your Apigee environment. Apigee sends transaction data from the API proxies in the environment to Cequence Bridge.

Environment file settings

The cq-cli utility and the bundle build scripts read the deployment settings from the .env file. For the manual method, the build scripts add the settings to the shared flow bundles. The following table describes each setting.

The following example shows a completed .env file.

APIGEE_ORG=example-org
APIGEE_ENV=prod
CEQUENCE_BRIDGE_ENDPOINT=https://bridge.example.com/api-transactions
CEQUENCE_SAMPLING_PER_MINUTE=
CEQUENCE_EXCLUDED_PROXIES=my-proxy-1,my-proxy-2

Removing the integration using the cq-cli utility

Use this procedure to remove the integration from your Apigee environment. The cq-cli utility detaches the Cequence shared flows from the flow hooks, undeploys the shared flows, and deletes the shared flows from your Apigee organization. Start this procedure from a terminal on your workstation.

1. From the terminal, change to the cequence-apigee-hybrid-plugin directory that contains the cq-cli utility and your .env file.

2. Remove the integration.

   ./cq-cli apigee destroy

   The terminal displays the progress of each operation. When the command completes, the last line of the output is similar to the following example.

   destroy: successfully deleted both sharedflow bundles from <project>

The Cequence shared flows are removed from your Apigee organization. API traffic continues through Apigee without the integration.

Installing the integration manually

Use the manual method when you want to upload and deploy the shared flows yourself in the Apigee UI. Manual installation consists of building the shared flow bundles on your workstation, uploading and deploying the shared flows, and then attaching the shared flows to the flow hooks of your environment.

Building the shared flow bundles

Use this procedure to build shared flow bundles that contain the settings for your environment. Start this procedure from a terminal on your workstation, in the directory where you downloaded the Cequence integration bundle.

1. From the terminal, extract the archive for your operating system and processor architecture. The archive names have the form cequence-apigee-hybrid-plugin-<operating system>-<architecture>.tar.gz.

   tar -xvf <archive name>

2. From the terminal, change to the cequence-apigee-hybrid-plugin directory that contains the cq-cli utility.

3. Make the cq-cli utility executable.

   chmod +x cq-cli

4. Create an environment file from the example file.

   cp .env.example .env

5. In a text editor, open the .env file and set the values for your environment. For a description of each setting, see Environment file settings in this article.

6. Initialize the cq-cli utility. The init command extracts the integration files, sets up the configuration, and validates your environment.

   ./cq-cli apigee init --tar ./cequence-apigee-hybrid-plugin.tar.gz

7. Change to the cequence directory.

   cd cequence

8. Add the settings from the .env file to the shared flow templates.

   bash script/render-templates.sh

   The terminal displays output similar to the following example. The sampling and endpoint lines show the values from your .env file.

   rendered cequence-post-proxy-sharedflow -> build/cequence-post-proxy-sharedflow
   rendered cequence-pre-proxy-sharedflow -> build/cequence-pre-proxy-sharedflow
   sampling: capped at 100pm
   endpoint: https://<fqdn>/api-transactions

9. Create the shared flow bundle files.

   bash script/zip.sh

   The terminal displays the following output.

   zipped cequence-post-proxy-sharedflow -> build/cequence-post-proxy-sharedflow.zip
   zipped cequence-pre-proxy-sharedflow -> build/cequence-pre-proxy-sharedflow.zip

10. Verify that the build directory contains the cequence-pre-proxy-sharedflow.zip file and the cequence-post-proxy-sharedflow.zip file.

    ls build

The cequence/build directory now contains shared flow bundles that include the Cequence Bridge endpoint, sampling, and excluded proxy settings for your environment.

Uploading and deploying the shared flows

Use this procedure to add the Cequence shared flows to your Apigee organization. Start this procedure in the Apigee UI of the Google Cloud console, with the Google Cloud project for your Apigee Hybrid organization selected. You need the shared flow bundle files from the cequence/build directory on your workstation.

1. From the Apigee navigation menu, select Proxy Development > Shared Flows.

   The Shared Flows page appears.

2. From the Shared Flows page, select Upload Bundle.

   The upload dialog box appears.

3. From the upload dialog box, select Browse, and then select the cequence-pre-proxy-sharedflow.zip file from the cequence/build directory.

4. Select Create.

   Apigee creates the shared flow.

5. To upload the cequence-post-proxy-sharedflow.zip file, repeat the previous three steps.

6. From the Shared Flows page, select cequence-pre-proxy-sharedflow.

   The cequence-pre-proxy-sharedflow page appears.

7. From the cequence-pre-proxy-sharedflow page, select Deploy.

   The deploy dialog box appears.

8. From the Revision list in the deploy dialog box, select the latest revision. From the Environment list, select your environment.
9. Select Deploy.
10. To deploy the cequence-post-proxy-sharedflow shared flow, select Proxy Development > Shared Flows from the Apigee navigation menu, select the shared flow, and then repeat the previous three steps.

Both Cequence shared flows are now deployed in your Apigee environment.

The shared flows do not process traffic until you attach the shared flows to flow hooks.

Attaching the shared flows to flow hooks

Use this procedure to run the Cequence shared flows for the API proxies in your environment. Start this procedure in the Apigee UI of the Google Cloud console, after you deploy both Cequence shared flows.

1. From the Apigee navigation menu, select Environments.
2. From the environment list, select the environment where you deployed the Cequence shared flows.
3. From the environment page, select the Flow Hooks tab.
4. From the Pre-proxy list, select cequence-pre-proxy-sharedflow.
5. From the Post-proxy list, select cequence-post-proxy-sharedflow.

Apigee now runs the Cequence shared flows for every API proxy in the environment and sends transaction data to Cequence Bridge.

Common problems and solutions

The following table describes common installation problems and the actions that resolve the problems.