Overview
Cequence integrates with the Broadcom API Gateway using the Cequence Broadcom API Gateway Policy Plugin. This Cequence component, installed as a Layer7 API Gateway Global Policy Fragment, captures request and response transaction metadata and, asynchronously, forwards this information via REST API to the UAP API Edge ingestion endpoint. This component does not interfere with the traffic flow. Transactions and transaction metadata forwarded to the Cequence Unified API Protection control platform are available for analysis by API Spartan and API Sentinel.
This document describes the integration of the Cequence Broadcom API gateway Plugin with a Broadcom API gateway deployed as an Appliance. It can also be used for integration with Broadcom gateway deployed as a docker container or in k8s. Integration is accomplished using the Broadcom Layer7 Policy Manager. Integration steps include configuring the Broadcom Layer7 Gateway to use the Cequence Broadcom Layer7 Gateway Plugin. The configuration will also include obtaining authentication credentials to your Cequence UAP control platform and modifying network ingress appropriately to allow for the transmission of transaction data. If you are tasked with upgrading your Cequence Broadcom custom Plugin, please refer to the Cequence Broadcom API Gateway Plugin Upgrade Steps Article.
Prerequisites
Deployment of the Cequence Broadcom API Plugin will require steps and configuration activity in both the Cequence Unified API Protection (UAP) platform via the Cequence Management Interface (CMI) and in the Broadcom Policy Manager.
Cequence UAP Platform
Your Cequence UAP control platform should be fully installed and confirmed as working before initiating the Broadcom API Gateway integration. If the Broadcom API Gateway is the first transaction data source to be integrated with your Cequence UAP platform, expect to work with a member of Cequence's Success Team to confirm that your UAP is working fully. You will need a Cequence UAP user account assigned with sufficient rights to create a client token for traffic ingestion.
Broadcom Layer7 API Gateway and Policy Manager
All aspects of your Broadcom API Gateway should be confirmed as working, including Broadcom API Gateway Policy Manager. You will need a 'root user' terminal access to your Gateway hosting platform sufficient to allow a download and installation of the Cequence Plugin components. These rights need to include the ability to move a file to folders: /opt/SecureSpan/Gateway/runtime/modules/lib/ and another file to: /opt/SecureSpan/Gateway/node/default/etc/conf/, and change file ownership and access (chmod).
Cequence Broadcom API Gateway Bundle
You will be downloading the Cequence Broadcom API Gateway Bundle, which includes the Policy Plugin executable JAR and configuration properties. Consult with your Cequence Success team member for the download location and access credentials. The bundle will be packaged as a compressed Tar archive (.tar.gz), and named similar to: "cequence-broadcom-plugin-version-tar.gz".
Network Rights
Cequence Plugin communicates with the Cequence UAP via HTTPS for API token retrieval and for sending transaction meta-data. There must be sufficient network ingress and egress permissions between the Broadcom API Gateway and the Cequence API Edge traffic ingestion endpoint for the Cequence Broadcom Plugin to function properly. There may be access changes required in the Broadcom Layer7 Gateway hosting environment to allow this. You must also be able to download the Cequence Plugin Bundle from an Amazon S3 bucket. The hosting environment for the Cequence Unified API Protection (UAP) control plane will generally have an "Allow List" that should be modified to allow communication between the UAP control plane and the Cequence Layer7 API Gateway Plugin. We will provide the UAP control plane endpoints below.
Deployment and Integration Steps
Cequence UAP Platform Parameters
API Client with Client Secret
You will need to create a Cequence UAP API 'clientId' and authenticating 'clientSecret' that will allow the Cequence Broadcom Policy Plugin to connect and send messages to the Cequence UAP Control platform traffic ingestion endpoint.
The 'clientId' is created in the Cequence Management Interface. Steps.
1. In the Cequence Management Interface, open General Settings: User Management. Click on the "Clients" tab.
2. Click on the "Add New Client" button in the upper right.
- Enter the client name and enable the "Traffic Ingestion" role.
- The default token lifespan is 1800 seconds. Edit this lifespan if you find it necessary.
The dialog will automatically close when you click the Save button. In the example below, the client is named “BC-L7Client”. Click Save to create this client.
Note: Record this client name. It will be used as the value for 'clientId' when configuring your Broadcom Layer7 Gateway Policy in later steps.
3. You will see the newly created client in the Clients list. Click on the eye icon under the Secret column to see and copy the secret. Record the value of this secret. It will be used as the value for 'clientSecret' when configuring your Layer7 Policy in later steps.
API Endpoints
You will also need to obtain two UAP API endpoint URLs. The URLs differ based on the type of UAP deployment. For example, If your UAP is deployed in Cequence SaaS instead of on-prem, the URL endpoint path will differ. Standard URL endpoint values are shown below but consult with your Cequence Success team member to confirm the correct values for your site.
For Cequence SaaS deployments, the values are as follows.
'authTokenUrl':
https://auth.<customer_name>.cequence.cloud/auth/realms/cequence/protocol/openid-connect/token
'transactionEndpointUrl':
https://edge.<customer_name>.cequence.cloud/api-transactions
For "on-premises" customer deployments, it will use the same domain name as the URL for the Cequence Management Interface.
'authTokenUrl':
https://auth.<uap_site_domain_name>/auth/realms/<REALM_NAME>/protocol/openid-token
'transactionEndpointUrl':
https://edge.uap_site_domain_name>/api-transactions
These values will be used when configuring your Broadcom Cequence Policy in subsequent steps.
Load Cequence Broadcom API Plug In
1. Log into your Broadcom Gateway as root user.
2. Working in the terminal window to your Broadcom Gateway platform, download the Cequence Broadcom API Gateway Plugin bundle to a temporary location
2.1. Uncompress and extract this file ('tar - xf..."). There will be two files in this bundle with names similar to the following.
- cequence-broadcom-plugin-1.0.jar
- custom_assertions.properties
3. Next, you will move and change permissions for 'cequence-broadcom-plugin-1.0.jar'
3.1. Copy this file to:
/opt/SecureSpan/Gateway/runtime/modules/lib/cequence-broadcom-plugin-1.0.jar
3.2. Change cequence-broadcom-plugin-1.0.jar file ownership and group ownership to 'layer7' and change the file permission to -rw-r--r-- or chmod 644. Use the commands below to change all permissions at once after completing steps 3.1 through 4.2.
4. Move, and change ownership and permissions for: 'custom_assertions.properties'.
4.1 Copy this file to: /opt/SecureSpan/Gateway/node/default/etc/conf/custom_assertions.properties.
4.2 Change only the ownership to 'layer7' and permissions to -rw-r--r-- or chmod 644. Log out of the root account. Use the commands below to change all permissions at once.
chmod 644 /opt/SecureSpan/Gateway/runtime/modules/lib/cequence-broadcom-plugin-1.0.jar
chown layer7:layer7 /opt/SecureSpan/Gateway/runtime/modules/lib/cequence-broadcom-plugin-1.0.jar
chmod 644 /opt/SecureSpan/Gateway/node/default/etc/conf/custom_assertions.properties
chown layer7 /opt/SecureSpan/Gateway/node/default/etc/conf/custom_assertions.properties
5. Log back into the Gateway using the ssgconfig account, then restart the Broadcom Layer7 Gateway and reboot the appliance.
Note: Restarting the Gateway and rebooting the Appliance are two separate functions. See the restart/reboot instructions in section: Restart and Reboot Broadcom Layer7 Gateway Using Text Menu at the end of this article.
The Cequence bundle is now loaded.
Broadcom Layer7 Policy Manager: Configure Cequence Custom Plugin
1. Log in to your Broadcom Layer7 API Gateway - Policy Manager.
2. You should see a home screen similar to the following. Notice, in the left side folder list, "Cequence Broadcom Plugin" under the folder Custom Assertions.
3. From the top (horizontal) menu, click "Tasks," then "Services and APIs" then "Create Policy."
4. This will open an empty Policy Properties dialog. Enter your policy Name. In this example we use "MyCequenceGlobalPolicy." Next set the Policy Type to "Global Policy Fragment" and set Policy Tag to "message-completed", and then Ok to save.
5. You should now see a view similar to the following. Note that "MyCequenceGlobalPolicy" has been added to the configured Policies for this (10.50.21.190:8443) Gateway in this example.
6. From the left-top-window drag the Cequence Custom-Assertions plugin to right-top-window. The result will look similar to the screenshot below.
7. In the right window, double-click to open the "Cequence.ai.broadcom.plugin" actions menu and select "Cequence Broadcom Plugin Properties".
The empty properties dialog will look similar to the following:
Fill in values for the following fields. Use the values you obtained from the Cequence UAP Platform Parameters and API Endpoints section.
'authTokenUrl':
'clientId':
'clientSecret':
'transactionEndpointUrl':
The result will look similar to the following:
Gateway Instance Name
You'll also need to assign your instance of the Layer7 Policy Plugin a discriptive identifying name, 'ceqGwName'. This name will help to identify the source of the transactions within the UAP. If multiple Broadcom Layer7 gateways are sending data to the Cequence UAP platform, then each gateway must be configured with its own unique name to help distinguish the transactions from each gateway. This will be important in future revisions of the plugin. Click OK to save the Cequence Broadcom Plugin configuration.
When you have completed all of the steps click Save and Activate. The Layer7 Policy Manager will validate the Cequence.ai.broadcom.plugin Policy. You'll see corresponding messages in the bottom right window under "Policy Validation Messages".
If the message says "Policy saved and made active", you are done with this deployment sequence of Cequence.
Verify UAP Integration
Send some test data to one of your backend applications.
You can quickly confirm that your Cequence UAP Platform is receiving a copy of the user-client to application-backend transactions through the Cequence Management Interface (UI).
1. Login into the Cequence Management Interface.
2. Open Runtime Inventory: API Inventory
2.1 From there, you should see the URL of the application that the Broadcom API Gateway has forwarded traffic for within the Cequence UAP Platform. Once the traffic is received, the UAP Platform will process this traffic and allow for it to be triaged accordingly.
3. You can also ensure traffic is being received by navigating to Diagnostis: System Diagnostics. Search by URL, and the traffic forwarded from the Broadcom API Gateway should show as Traffic Received.
4. You can verify that your Cequence Broadcom Plugin is communicating with your Cequence UAP Appliance by using the Broadcom L7 API Gateway Policy Manager. Click the View drop-down menu and select View Logs. If communication is established, your output will look similar to the following.
2023-10-16T09:11:15.243-0700 WARNING 721560 com.l7techcom.cequence.ai.LoggingServiceInvocation: Time to fetch token
2023-10-16T09:11:15.244-0700 WARNING 721560 com.l7techcom.cequence.ai.LoggingServiceInvocation: getToken uri:https://auth.yourdomain.com/auth/realms/cequence/protocol/openid-connect/token
2023-10-16T09:11:15.244-0700 INFO 721560 STDOUT: grant_type=client_credentials&scope=profile&client_secret=********************************&client_id=***********
2023-10-16T09:11:15.269-0700 WARNING 721560 com.l7techcom.cequence.ai.LoggingServiceInvocation: txnBatchProcess: exception com.google.gson.stream.MalformedJsonException: Use JsonReader.setLenient(true) to accept malformed JSON at line 2 column 2 path $
You are all done.
Restart and Reboot Broadcom Layer7 Gateway Using Text Menu
The 'ssgconfig' text menu provides one way to restart the gateway and then reboot the appliance. You may choose to use this method.
1. Log back into the Broadcom GW hosting platform, this time as user 'ssgconfig'.
This account should open to a text menu supporting a host appliance configuration. You should see a menu similar to the following.
2. Select option 2 ("Display Layer7 API Gateway configuration menu").
To display a second menu:
3. Enter '7' ("Manage Layer7 API Gateway status") and see the current status. A running status will look similar to the snapshot below:
4. Click 'Enter' once more for options, then select '2' to restart the Layer7 API Gateway.
Once the restart is initiated, you should see the following:
5. Now enter 'X' and 'X' again to go to the top menu, then select option 'R' ("Reboot the Layer7 API Gateway appliance (apply the new configuration)") to do just that.