Article Purpose

This article provides instructions for passive integration of the Cequence Unified API Protection (UAP)  to an existing Apigee Edge or Apigee OPDK installations. 

• See Apigee Integration Overview for a general description of how Cequence UAP works and integrations with Apigee environments. 
• See Apigee Integration Steps: Inline Defender for steps to integrate Cequence Defender into your Apigee environment. 

Notes:

• The reader should be familiar with their own existing or anticipated Apigee configuration.
• Code and templates to be adapted application are attached to this article.  
• The Cequence Customer Success Team will assist with the deployment to match your requirements.
• This article uses Apigee Edge UI for illustration. Steps in other Apigee packages are similar.

Overview

There are two basic approaches for integrating Cequence Unified API Protection (UAP) into an Apigee proxy configuration:  inline, using Cequence Defender, and passive, allowing the Apigee gateway to send transactions directly to the Cequence Unified API Edge (traffic ingestion) API endpoint. 

Cequence UAP passive integration supports 'read-only' analysis by Cequence UAP components and modules.  Inline integration supports both analysis and active mitigation of suspect transactions. In passive integration,  request/response transaction information is captured and sent to Cequence API Edge endpoint using Apigee Shared Flow.  This approach supports API discovery and risk analysis of APIs by both API Sentinel (Runtime Inventory) and  API Spartan (Threat Protection).

Cequence -  Apigee:  Shared Flow Integration

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

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

Apigee's data flow steps:

>>  Requests are received at the ProxyEndpoint and are processed through handlers ("PreFlow", "ConditionalFlows",  and "PostFlow") and forwarded to the TargetEndpoint handlers (with the same names), and finally delivered to  the actual backend service.

>>>> For Request data, Cequence Shared Flow snippets are hooked into ProxyEndpoint PreFlow.

>>  Responses are processed in a similar manner with the addition of one more handler ("PostClientFlow") after PostFlow. 

>>>> For Response data, Cequence Shared Flow snippets are hooked into  TargetEndpoint PostFlow. 

Passive (Shared Flow) Integration Data Flow

1.  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. 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 in turn makes a call asynchronously 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 Cequence UAP tenant and then posts combined transaction data and metadata (request and response) to your Cequence UAP tenant endpoint. 
   
   
4. Apigee continues the response back to the client. 

Passive Mode Integration Steps

1. Import 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 first navigating to Develop::Shared Flows, and clicking the +Shared Flow menu (upper right), and then Upload bundle... and Create to complete the process.  Do this once for each of the three zip bundles to create the new Shared Flow bundles.  The result will look similar to the following:

 

2. Determine Cequence UAP API Edge or Bridge Endpoint and Cequence UAP Authentication Credentials

a) Traffic Ingestion Endpoint (a.k.a Cequence UAP 'API Edge' endpoint). If you are subscribed to a Cequence SaaS tenant, the Cequence Customer Success team will provide this to you. 

Generic format (subject to change):

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

Note: If you are using the Cequence Bridge, then the above traffic ingestion endpoint will need to point to the bridge.

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

b) Authentication Endpoint. If you are subscribed to a Cequence SaaS tenant, the Cequence Customer Success team will provide this to you.

Generic format (subject to change):

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

c) Create an API client and note the Authentication credentials.

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.

3.  Review Cequence Bundles

3.0 Create Cache as shown below:

Under Admin>Environments>Cache

Create a new cache with name - cequence-token-cache and expiration as 5 mins

3.1 cequence-sharedflow-pre-proxy - Policy:  CopyRequestParam

Open  cequence-sharedflow-pre-proxy, then switch to the Develop tab. You'll see one Policy "CopyRequestParams".  This policy simply saves the Request information to RequestCopy.

 

3.2 cequence-sharedflow-sharedflow-post-target-unified - Policies

Navigate back to Shared Flows, then open cequence-sharedflow-post-target-unified, and switch to the Develop tab.   Click on 'default' under Shared Flows.  There will be three Policies:  Base64EncodePayloads, BuildCalloutRequest and CallCequenceAPIProxy.

In the CallCequenceAPIProxy policy, set a Cequence header named cq-auth-cap in line number 9. This header can take any value.

Note: This header and value are unique to each client, and are used to authenticate with the Cequence API Proxy. Without this header, the call from cequence-shared-post-target-unified to cequence-api-proxy results in an authentication failure and API Transaction metadata does not  post to the Cequence UAP platform.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceCallout async="false" continueOnError="true" enabled="true" name="CallCequenceAPIProxy">
    <DisplayName>CallCequenceAPIProxy</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="notificationRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Set>
            <Headers>
                <Header name="cq-auth-cap">cequence</Header>
            </Headers>
            <Payload contentType="application/json">{notificationRequestPayload}</Payload>
            <Verb>POST</Verb>
        </Set>
    </Request>
    <LocalTargetConnection>
        <APIProxy>cequence-api-proxy</APIProxy>
        <ProxyEndpoint>default</ProxyEndpoint>
    </LocalTargetConnection>
</ServiceCallout>

3.3 cequence-api-sharedflow - Policies

Navigate back to Shared Flows, then open cequence-api-sharedflow, and switch to the Develop tab. Click on 'default' under Shared Flows. There will be seven Policies: ExtractAccessTokenFromCallout, GetAccessToken, LookupCacheGetToken, PopulateCacheStoreToken, SendRequestResponse, SetAuthenticationFlag, and SetCalloutAccessToken.

4. Configure GetAccessToken

Set the authentication credentials and endpoint.  In this same Develop view, click on Policy GetAccessToken to open it for view and edit. The middle columns will contain a policy overview with its name, type (ServiceCallout) and HTTP Target for authentication. Underneath that is the XML code.  The column to the right is the Property Inspector. 

Using either the Property Inspector form, or directly in the XML, Set the form values to the  'client_id',  'client_secret' and the authentication endpoint (HTTP Target) URL.  In the example below, the XML has been modified for client_id "acmecorp-ingestion-client", a client_secret, and an authentication URL corresponding to a fictional Acme Corp tenant. 

<?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>
         <FormParam name="client_id">acmecorp-ingestion-client</FormParam>
         <FormParam name="client_secret">aaaaaaaa-bbbb-cccc-dddd-ba1927183371</FormParam>
         <FormParam name="grant_type">client_credentials</FormParam>
       </FormParams>
       <Verb>POST</Verb>
     </Set>
     <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   </Request>
   <Response>tokenCalloutResponse</Response>
   <HTTPTargetConnection>
     <Properties/>
     <URL>https://auth.acmecorp.1.cequence.cloud/auth/realms/cequence/protocol/openid-connect/token</URL>
   </HTTPTargetConnection>
</ServiceCallout>

Save your changes. Navigate back to Shared Flows.

5. Configure SendRequestResponse

We'll now set the endpoint for sending the Request/Response message.  Return to the 'cequence-api-sharedflow' Develop view.  Click on Policy 'SendRequestResponse'.

 

 

Here we only have to modify the HTTP Target Connection and set it to the Target Ingestion (API-Edge or Bridge) endpoint you obtained in step 2(a).

6. Configure PopulateCacheStoreToken

Update the <TimeoutInSec> value from the default 300 to the one set for the authentication token TTL set on the UI. This will set the local cache TTL on Apigee.

 

7.  Deploy modified bundles to the appropriate environment(s) for your activity

Open each Cequence Shared Flow bundle and select the Deployment action menu, and deploy to dev, prod or test environments depending on the API proxy traffic to be ingested into Cequence. Deploying to an environment makes the Shared Flow bundle accessible to that environment but does not yet 'hook' it in.  That's the next step. 

8.  Hook the modified Shared Flow bundle 

In the Apigee UI, navigate to Admin:: Environments: Flow Hooks.  Select the deployment environments you deployed these module to in the previous step.  Hover over the 'pre-proxy' row, click the edit pen, and you should see a dialog with a selector, providing you with the choice of the two bundles. 

 

 

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

 

9. Create a new API Proxy: cequence-api-proxy

cequence-api-proxy (contained in zip file cequence-api-proxy.zip) is a dedicated Cequence API proxy that will be deployed in your Apigee environment. Upload the Proxy zip bundle and create the proxy in the chosen environment (dev, prod or test).

Set Header in Cequence API proxy for Authentication
Under the proxy endpoint default, change the header on line number 10 as shown in the following code sample. Note that this is the same header name set up previously in this procedure.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>AM-NotificationRequest</Name>
            </Step>
            <Step>
                <Name>RF-CequenceProxyAuthenticationFailure</Name>
                <Condition>request.header.cq-auth-cap is NULL</Condition>
            </Step>
            <Step>
                <Name>FC-CequencePostFlow</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/cequence-api-request</BasePath>
        <VirtualHost>secure</VirtualHost>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

 

cequence-sharedflow-post-target-unified shared flow deployed in one of the earlier steps internally makes an asynchronous call to this cequence-api-proxy and closes the request.

cequence-api-proxy in turn calls the cequence-api-sharedflow that has the logic of access token retrieval, caching of tokens and posting of API transaction data to the Cequence traffic ingestion endpoint.

 

 

10. Installation and Deployment is Complete

The  Cequence UAP Passive Shared Flow components are now installed, deployed, and hooked in to your selected environment are part of the processing flow for every API proxy deployed to that environment.  They will act on all transactions and provide Cequence UAP  with transaction data.

Use the Apigee Trace feature to confirm and monitor 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 (dev, prod or test) automatically execute it. This helps Cequence get a feed of traffic from all API proxies deployed in that specific environment.

However, for deployments where only selective APIs need to send a feed of traffic data into Cequence, the shared flow bundles should not be attached to the global Flow hooks, but instead be invoked through the FlowCallout Policy (as shown below)the respective stage (pre-proxy and post-target in our case) within the specific API Proxy.

 

The  FlowCallout Policy(cequence-sharedflow-pre-proxy) should be placed as the first policy in the Request flow of Pre flow at the Proxy Endpoint

 

Similarly, The  FlowCallout Policy(cequence-sharedflow-post-target-unified) should be placed as the first policy and should be executed in the response flow of postflow at the Target Endpoint 

 

 

Also if the cequence-sharedflow-pre-proxy and  cequence-sharedflow-post-target-unified shared flows are applied as flows hooks at the envirorment level and where only selective APIs need to send a feed of traffic data into Cequence, the make the below changes - 

For cequence-sharedflow-pre-proxy shared flow

 

For cequence-sharedflow-post-target-unified shared flow

 

Attachments

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

Version History

Date	Version	Notes
Aug 6, 2025	11	Revised Instructions to reflect changes in Cequence Plugin Package
Mar 31, 2025	10	Added header based Authentication for Cequence API Proxy
Jan 8, 2025	9	Updated the version field to 1.1 to add support for new API Edge payload format in UAP 7.5.0 and above
Aug 30, 2024	8	Added a) Section 3.0 To Create Cache  b) steps and screenshots that need to be followed for deployments where only selective APIs need to send traffic data into Cequence c) Corrected the numbering
Jun 20, 2024	7	Updated to add Apigee Tracing callout.
Feb 6, 2024	6	Updated to update newer traffic ingestion and auth endpoint paths.
Nov 14, 2023	5	Updated with newer screenshots of SharedFlow.
Sep 19, 2023	4	Updated for caching tokens across multiple calls.
July 25, 2023	3	Updated for newer FlowCallout policy support.
Feb 4, 2023	2	Updated with improved layout and procedural steps.
Jan 14, 2023	1	Initial version.