This article describes how to configure a passive integration between the Cequence Unified API Protection (UAP) platform and an existing Apigee Edge or Apigee OPDK installation. In passive mode, the Apigee gateway forwards transaction data to the Cequence UAP platform for API discovery and security analysis without inline traffic inspection.

For a general overview of Cequence UAP and Apigee integration options, see Apigee integration overview. For inline integration using Cequence Defender, see Apigee integration steps: inline Defender.

Overview

There are two basic approaches for integrating the Cequence UAP platform into an Apigee proxy configuration: inline, using Cequence Defender, and passive, enabling the Apigee gateway to send transactions directly to the Cequence UAP platform's traffic ingestion API endpoint.

The Cequence UAP platform's passive integration supports read-only analysis by Cequence UAP components. Inline integration supports both analysis and active mitigation of suspect transactions. In a passive architectue, Apigee Shared Flow captures request/response transaction information and sends the data to the Cequence API Edge endpoint. This approach supports API discovery and risk analysis by both Detection (Runtime Inventory) and Mitigation (Threat Protection).

Cequence passive integration support limitations

The following limitations apply to passive integration deployments.

• Request and response bodies exceeding 32KB are truncated, limiting data to 32KB for the Cequence UAP platform and adding the header cq-body-truncated=true.
• Request and response body capture is skipped for transactions from streamed APIs.

Cequence–Apigee Shared Flow integration

Apigee Shared Flow is a bundle of policies and resources, including code scripts, that may be used with multiple Apigee API proxies. Cequence passive mode integration uses the Apigee Shared Flow feature to insert code into request and response transaction handling.

The Cequence UAP shared flow scripts obtain request/response transaction information, parse each transaction to extract key fields, and forward messages to the Cequence UAP API Edge traffic ingestion endpoint. Once the Cequence UAP platform receives this information, analysis proceeds independently and asynchronously to the actual transaction data flow.

Apigee processes requests received at the ProxyEndpoint through the PreFlow, ConditionalFlows, and PostFlow handlers, then forwards them to the TargetEndpoint handlers of the same names, and finally delivers them to the backend service.

• For request data, Cequence Shared Flow snippets hook into ProxyEndpoint PreFlow.
• For response data, Cequence Shared Flow snippets hook into TargetEndpoint PostFlow.

Passive (Shared Flow) integration data flow

1. The client sends an API request to the Apigee API ProxyEndpoint. Cequence Shared Flow in PreFlow (cequence-sharedflow-pre-proxy) captures and saves key request data and metadata. Request flow continues through Apigee request handlers.
2. Apigee delivers the request to the API backend server.
3. The API backend server processes the request and responds. Cequence Shared Flow in PostFlow (cequence-sharedflow-post-target-unified) captures key response data and metadata. This Shared Flow makes an asynchronous call to a dedicated API proxy configured on Apigee, cequence-api-proxy, which invokes the SharedFlow (cequence-api-sharedflow) that makes the actual callout to Cequence. The cequence-api-sharedflow authenticates to the Cequence UAP tenant and posts combined transaction data and metadata to your Cequence UAP tenant endpoint.
4. Apigee continues the response back to the client.

Before you begin

This procedure assumes familiarity with your Apigee configuration. You will need the Cequence Shared Flow and API proxy bundle, your Cequence client ID/secret, authentication endpoint, and transaction endpoint. The Cequence Customer Success team can assist with deployment to match your requirements. Screenshots in this article use the Apigee Edge UI; steps in other Apigee packages are similar.

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

Passive mode integration steps

Complete the following steps to install, configure, and deploy the Cequence passive integration components in your Apigee environment.

1. Importing Cequence Shared Flow bundles

Cequence provides templates for the Shared Flow configurations.

• Download the Cequence plugin package archive and expand it. The plugin package contains the following four files: cequence-api-proxy.zip, cequence-api-sharedflow.zip, cequence-sharedflow-post-target-unified.zip, and cequence-sharedflow-pre-proxy.zip.
• Upload cequence-api-sharedflow.zip, cequence-sharedflow-post-target-unified.zip, and cequence-sharedflow-pre-proxy.zip to Apigee by navigating to Develop > Shared Flows, selecting the +Shared Flow menu (upper right), then Upload bundle and Create. Repeat for each of the three zip bundles.

2. Determining endpoints and credentials

a) Traffic ingestion endpoint (the Cequence UAP API Edge endpoint). Your Cequence Customer Success team will provide this for SaaS tenants.

Generic format:

https://edge.{cequence-provided-domain}/api-transactions

Note: When you use Cequence Bridge, point the traffic ingestion endpoint to the Bridge instead:

https://<Bridge-FQDN-or-Bridge-IP>/api-transactions

b) Authentication endpoint. Your Cequence Customer Success team will provide this for SaaS tenants.

Generic format:

https://auth.{cequence-provided-domain}/auth/realms/cequence/protocol/openid-connect/token

3. Reviewing Cequence bundles

Navigate to Admin > Environments > Cache and create a new cache with the name cequence-token-cache and an expiration of five minutes.

4. Configuring GetAccessToken

Set the authentication credentials and endpoint. In the Develop view, select Policy GetAccessToken to open it. Use the Property Inspector form or edit the XML directly to set the client_id, client_secret, and authentication endpoint (HTTP Target) URL.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceCallout async="false" continueOnError="true" enabled="true" name="GetAccessToken">
    <DisplayName>GetAccessToken</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="tokenCalloutRequest">
        <Set>
            <FormParams>
                <!--Add the Cequence Generated Client ID and Client Secret-->
                <FormParam name="client_id">test-uap</FormParam>
                <FormParam name="client_secret">xxxxxx</FormParam>
                <FormParam name="grant_type">client_credentials</FormParam>
            </FormParams>
            <Verb>POST</Verb>
        </Set>
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>tokenCalloutResponse</Response>
    <HTTPTargetConnection>
        <Properties/>
        <!--Add the Cequence Authentication Endpoint-->
        <URL>https://auth.common.xxxxxx/protocol/openid-connect/token</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Save your changes and navigate back to Shared Flows.

5. Configuring SendRequestResponse

Set the endpoint for sending the request/response message. Return to the cequence-api-sharedflow Develop view and select Policy SendRequestResponse.

Modify the HTTP Target Connection to point to the traffic ingestion (API Edge or Bridge) endpoint obtained earlier in this procedure.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceCallout async="false" continueOnError="true" enabled="true" name="SendRequestResponse">
    <DisplayName>SendRequestResponse</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="notificationRequest">
        <Set>
            <Headers>
                <Header name="Authorization">Bearer {calloutAccessToken}</Header>
            </Headers>
            <Payload contentType="application/json">{notificationRequestPayload}</Payload>
            <Verb>POST</Verb>
        </Set>
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>cequenceResponse</Response>
    <HTTPTargetConnection>
        <Properties/>
        <!--Add the API Edge or Cequence Bridge Transaction Endpoint-->
        <URL>https://xxxxxxx/api-transactions</URL>
    </HTTPTargetConnection>
</ServiceCallout>

6. Deploying modified bundles to the appropriate environment

• Open each Cequence Shared Flow bundle, select the Deployment action menu, and deploy to the dev, prod, or test environment corresponding to the API proxy traffic you want to ingest into Cequence.
• Deploying to an environment makes the Shared Flow bundle accessible to that environment but does not yet hook the bundle in. That is the next step.

7. Hooking the modified Shared Flow bundle

In the Apigee UI, navigate to Admin > Environments > Flow Hooks. Select the deployment environment you used in the previous step. Hover over the pre-proxy row, select the edit icon, and choose from the bundle selector dialog.

Note: Resources uploaded or deployed to the same environment will appear in the drop-down menu.

• For Pre-proxy, choose cequence-sharedflow-pre-proxy.
• For Post-target, choose cequence-sharedflow-post-target-unified.

8. Creating a new API proxy: cequence-api-proxy

• cequence-api-proxy (contained in cequence-api-proxy.zip) is a dedicated Cequence API proxy that deploys in your Apigee environment. Upload the proxy zip bundle and create the proxy in the chosen environment.
• Set the header in the Cequence API proxy for authentication. Under the proxy, update the FC-CequencePostFlow file for the SharedFlowBundle and set it to your appropriate cequence-api-sharedflow.
• cequence-sharedflow-post-target-unified makes an asynchronous call to cequence-api-proxy and closes the request. cequence-api-proxy in turn calls cequence-api-sharedflow, which handles access token retrieval, token caching, and posting API transaction data to the Cequence traffic ingestion endpoint.

9 (Optional). Enabling streaming on the client proxy

When your API proxies handle payloads that may exceed Apigee's default 10MB limit, enable request and response streaming on the client proxy.

1. Navigate to the client proxy in the Apigee UI.

2. Open the default section. Inside the <HTTPProxyConnection> element, add the streaming properties shown below and save.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <ProxyEndpoint name="default">
       <PreFlow name="PreFlow">
           <Request/>
           <Response/>
       </PreFlow>
       <Flows/>
       <PostFlow name="PostFlow">
           <Request/>
           <Response/>
       </PostFlow>
       <HTTPProxyConnection>
           <BasePath>/your-base-path</BasePath>
           <Properties>
               <Property name="request.streaming.enabled">true</Property>
               <Property name="response.streaming.enabled">true</Property>
           </Properties>
           <VirtualHost>secure</VirtualHost>
       </HTTPProxyConnection>
       <RouteRule name="default">
           <TargetEndpoint>default</TargetEndpoint>
       </RouteRule>
   </ProxyEndpoint>

10. Installation and deployment is complete

The Cequence UAP passive Shared Flow components are now installed, deployed, and hooked into your selected environment. They act on all transactions in that environment and provide the Cequence UAP platform with transaction data. Use the Apigee Trace feature to verify and monitor the installation.

Important notes

By design in Apigee, once a shared flow bundle is attached to the global flow hooks (Admin > Environments > Flow hooks), all API proxies in that environment automatically execute the shared flow bundle. This enables the Cequence UAP platform to receive a feed of traffic from all API proxies in that environment.

For deployments where only selective APIs need to send traffic data to Cequence, do not attach the shared flow bundles to global flow hooks. Instead, invoke them through the FlowCallout Policy at the respective stage within the specific API proxy.

Place the FlowCallout Policy (cequence-sharedflow-pre-proxy) as the first policy in the Request flow of PreFlow at the Proxy Endpoint.

Place the FlowCallout Policy (cequence-sharedflow-post-target-unified) as the first policy in the Response flow of PostFlow at the Target Endpoint.

When the shared flows are applied as flow hooks at the environment level and you need only selective APIs to send traffic to Cequence, make the following changes.

For cequence-sharedflow-pre-proxy:

For cequence-sharedflow-post-target-unified:

Troubleshooting

The following are common issues encountered during passive integration setup.

• 413 – Request Entity Too Large on the client proxy: Ensure streaming is enabled for your client proxy (see step 9).
• 401 – Unauthorized: Verify the credentials configured in the cequence-api-sharedflow GetAccessToken policy.
• Transactions do not appear in the Cequence UAP platform despite clean trace output: Verify that the pre-proxy and post-target shared flow entries are added to the Flow Hooks in the correct environment.

Attachments

The plugin package contains the following bundles.

• Cequence Sharedflow Pre-Proxy
• Cequence API Sharedflow
• Cequence Sharedflow Post-target Unified
• Cequence API Proxy