Article Purpose
This article provides instructions for passive integration of the Cequence Unified API Protection (UAP) to an existing Apigee Edge, Apigee X, or a hybrid Apigee installation.
- 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
-
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.
-
Apigee delivers the request to the API backend server.
-
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.
- 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 templates, expand, and import into your Apigee tenant for reference and source copy.
Upload each 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 zip bundle to create the new Shared Flow bundles. The result will look similar to the following:
2. Determine Cequence UAP API Edge endpoint and authentication credentials
Cequence Customer Success team will provide Cequence UAP tenant URLs for:
a) Traffic Ingestion Endpoint (a.k.a Cequence UAP 'API Edge' endpoint).
Generic format (subject to change):
https://edge.{cequence-provided-domain}/api-transaction
b) Authentication Endpoint.
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:
Client ID (client name on the UI) and Client Secret (client secret on the UI).
Use instructions found here: Cequence Security Unified Dashboard: API Access Authentication,
We will use these credentials and endpoints in a subsequent step.
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.
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 five Policies: ExtractAccessTokenFromCallout, GetAccessToken, LookupCacheGetToken, PopulateCacheStoreToken and SendRequestResponse.
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 nonsense 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 and set it to the Target Ingestion (API-Edge) endpoint you obtained in step 1.
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).
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 |
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. |