Skip to main content
API Gateways

Search

IBM API Connect

© 2024 Cequence Security. All Rights Reserved.

IBM API Connect

  • Updated on
  • ~ minute read
Download PDF

IBM API Connect is a comprehensive API management platform that empowers administrators to govern the full API lifecycle. The proxy capabilities of IBM API Connect act as an intelligent intermediary between API consumers and backend services by intercepting incoming requests and outgoing responses, enabling a wide range of transformations and policies. This interception also facilitates monitoring and analytics, providing administrators with critical insights into API usage and performance.

This article describes how to integrate IBM API Connect with the Cequence Unified API Protection (UAP) platform in order to discover and protect the APIs that are managed by IBM API Connect. You can implement Custom Gateway Scripts and Global Policies to extend the gateway functions in order to change the API flow to meet specific requirements and use cases.

To integrate with the Cequence UAP platform, IBM API Connect needs to send all request and response data to the Cequence UAP platform's traffic ingestion API by making use of Custom Global Policies.

The custom Global Policies in IBM API Connect use Gateway Scripts that synchronously processes request and response data. The data is sent to the Cequence Bridge in the required JSON format before being sent to the Cequence API Edge server, which processes the transactions and provides insights into the API traffic.

High-Level Architecture

image-20250321-023229.png

API Call Flow

Note: The term "Assembly" refers to a set of policies and configurations applied to an API endpoint within the API Gateway. Assemblies are collections of instructions that dictate how to handle an API request and response.

  1. The IBM API Connect API Gateway receives incoming API requests. The pre-hook global policy intercepts each request, capturing the request payload and metadata.
  2. The request flows through the Assembly for further processing and moves on to the Backend/Target Applications.
  3. A response is received from the origin server. Any applicable policies in the Assembly execute and the post-hook global policy captures the response payload and metadata.
  4. The Request and Response Payload and metadata are synchronously posted to the Cequence Bridge, which forwards the transaction to the Cequence UAP Edge for threat analysis, detection, and mitigation.
  5. Cequence Bridge synchronously responds with a success. If the call to Bridge fails, it happens silently without disrupting the actual traffic.
  6. The origin server's response is returned to the client.

Terms used in this article

Catalog: A Catalog is a staging target that behaves as a logical partition of the gateway and the Developer Portal. The URL for API calls and the Developer Portal are specific to a particular Catalog. In a typical configuration, an API provider organization uses a development Catalog to test APIs under development and a production Catalog to host APIs that are ready for full use. A common approach is to have a development cloud with a development Catalog, a few test Catalogs, and a production cloud with a dedicated test Catalog.

Space: A Space partitions a Catalog to enable multiple product teams to manage Products and APIs independently in a single Catalog. A Space behaves like a sub-catalog, but the Products and APIs in all Spaces in a given Catalog are published to the same developer portal.

Prerequisites

  • IBM APIC SaaS tenant.
  • IBM APIC CLI V10.
  • The jq filtering utility. Download jq from the repository.
  • Cequence UAP platform release 7.3 or newer.
  • A Client ID and Client Secret generated from the Cequence UAP platform UI.
  • Cequence Bridge deployed close to the Customer's IBM API Connect Tenant.
  • Cequence Bridge Transactions Endpoint.

Detailed Prerequisites Setup

The following procedures establish several of the prerequisites.

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

IBM APIC CLI V10

  1. Download the APIC toolkit from the API Connect dashboard. Click Tools For Download.

    image-20250320-090133.png

  2. Click the link for the operating system of the host where the APIC toolkit is going to run.

  3. Run the following commands to set environment variables and create the proper directory structure.

    mkdir -p $HOME/cequence && cd "$_"
export CEQUENCE_HOME=$(pwd)
cp <DOWNLOAD_DIR>/cequence-apic-<version>.tar.gz $CEQUENCE_HOME
tar -xvzf cequence-apic-<version>.tar.gz
cd cequence-apic
export CEQUENCE_APIC_HOME=$(pwd)
mkdir $CEQUENCE_APIC_HOME/cli

  4. Choose your operating system.

    • On Linux, copy the toolkit-linux.tgz archive file downloaded from the IBM dashboard to the $CEQUENCE_APIC_HOME/cli folder.

    • On MacOS, copy the toolkit-mac.zip archive file downloaded from the IBM dashboard to the $CEQUENCE_APIC_HOME/cli folder.

  5. Extract the archive.

    • On Linux, run the following command. 
      tar -xvzf toolkit-linux.tgz
    • On MacOS, run the following command. 
      unzip toolkit-mac.zip

The apic CLI tool is now in the cli folder.

Plugin Installation

Installing the plugin takes place over several tasks that you perform in sequence.

Downloading and extracting the plugin archive file

  1. Download the compressed plugin archive file.
  2. Extract the compressed archive file to the $CEQUENCE_APIC_HOME directory.

Setting up the IBM APIC Cequence .env file

Verify that your environment meets all the pre-requisites before beginning this procedure.

  1. From the $CEQUENCE_APIC_HOME/scripts directory, run the following command to copy the .env_example file to a new .env file.

    cp .env_example .env

  2. Set environment variables as required by your IBM API Connect Environment

    • To create a new API key when needed, click the user icon in the top right corner and click My API Keys, then click Add.
      Screenshot 2025-04-15 at 4.07.31 PM.png
    • Copy the API Key and note it fo later use. Set the value of the CEQUENCE_IBM_SERVER attribute in the .env file to the URL after the --server string in the Use API key with APIC CLI field.My-API-Keys-APIC.png
      Screenshot 2025-04-15 at 4.15.13 PM.png
    • Navigate to APIC Settings and set a value for the CEQUENCE_IBM_ORGANIZATION attribute. The organization name is a short identifying label for your organization.

Key Attributes in the .env File

# Whether to deploy to all catalogs and spaces
CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES="false"
# Whether to delete the Cequence global policies (for rollback)
CEQUENCE_IBM_DELETE_GLOBAL_POLICIES="false"
# Whether to skip deploying the global policies to the sandbox catalog
CEQUENCE_SKIP_SANDBOX_CATALOG="false"
# Whether to enable x-cequence response headers for debugging
CEQUENCE_ENABLE_CUSTOM_RESPONSE_HEADERS="false"
# Cequence Bridge URL provided by Cequence team
CEQUENCE_BRIDGE_URL="https://bridge.org.cequence.ai/api-transactions"

To deploy to selected catalogs and spaces, create a config.jsonc file by copying the template to a new file named config.jsonc.

cp config-template.jsonc config.jsonc

The following excerpt are sample contents of a config.jsonc file.

{
  // Catalog where all spaces are included for deployment
  "sandbox": [], // NOTE: Notice that the value is an empty array
  "catalog_1": [],
  "catalog_2": [],
  // Catalog where only specific spaces are included for deployment
  "catalog_3": ["space_1"], // NOTE: Notice that the value is an array of spaces
  "catalog_4": ["space_1", "space_2"]
}

Log on to the IBM API Connect CLI

Run the following commands from a terminal to log on to the IBM API Connect CLI.

  1. From the $CEQUENCE_APIC_HOME/cli directory, run the following command. 
    source $CEQUENCE_APIC_HOME/scripts/.env
  2. Choose an operating system.
    • On Linux, run the following command. 
      ./apic login --sso --context provider --server $CEQUENCE_IBM_SERVER --apiKey $CEQUENCE_IBM_API_KEY
    • On MacOS, run the following commands. 
      chmod +x apic
      xattr -d com.apple.quarantine apic
      sudo ./apic login --sso --context provider --server $CEQUENCE_IBM_SERVER --apiKey $CEQUENCE_IBM_API_KEY

Cloud Administration Commands

  1. Run the following command to get the names of the configured gateway services.
    ./apic configured-gateway-services:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER --scope catalog --catalog sandbox
  2. Set the value of the CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES environment variable to the first result of the previous command. 
    export CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES=apic-gwv6a-xa3
  3. Run the following command to list existing global policies. 
    ./apic global-policies:list-all --scope catalog --catalog sandbox --server $CEQUENCE_IBM_SERVER --org $CEQUENCE_IBM_ORGANIZATION --configured-gateway-service $CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES

Deployment Configuration

You can apply policies with one of two different approaches.

Approach 1: Global to all Catalogs and Spaces

To deploy Cequence Global Policies to all catalogs and spaces, set the value of the CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES flag in the .env file to true.

Approach 2: Specific Catalogs and Spaces

  1. To deploy the Cequence Policies to specific catalogs and spaces, set the CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES flag as false.
  2. Set up the config.jsonc file in the $CEQUENCE_APIC_HOME/scripts directory.
    cp config-template.jsonc config.jsonc
  3. To get the list of catalogs, run the following command from the $CEQUENCE_APIC_HOME/cli directory. 
    ./apic catalogs:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER
  4. To get the list of spaces within a catalog, run the following command. 
    ./apic spaces:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER --catalog <catalog-name>

Excluding APIs where the Cequence global policy must be disabled

To exclude specific APIs, add a property called isExcludedFromCequenceGlobalPolicy with a value of true at the API level or Catalog level. This property can only be modified from the IBM APIC UI.

  1. From the Gateway tab, click the + icon next to Properties.
  2. Add the name isExcludedFromCequenceGlobalPolicy.
  3. Add the value true.
  4. Click Add.
  5. Click Save.

Installing Cequence global policies

Global Policies can only be deployed via the CLI. Run the following commands from the $CEQUENCE_APIC_HOME/scripts directory.

chmod +x *.sh
./deploy.sh

Monitor the output for any errors. When the script finishes running, check for a success message.

Test the plugin setup

Testing the Integration

Send a curl or Postman request to any API deployed in a space or catalog where the plugin or policy is enabled.

When the value of CEQUENCE_ENABLE_CUSTOM_RESPONSE_HEADERS is true, the response headers will contain x-cequence-headers.

Verify the Transactions in UAP Platform

Navigate to the transactions view of the Cequence UAP platform to confirm that transactions appear.

Rollback

Use the rollback script to delete all the Cequence resources you created. You can also delete the API, Product, Consumer Org, Catalog, and User Registry manually on the dashboard.

Note: Global policies can only be removed from the CLI.

To use the script to roll back the installation, set the value of the CEQUENCE_IBM_DELETE_GLOBAL_POLICIES variable to true, then run the script from the $CEQUENCE_APIC_HOME/scripts directory.

./rollback.sh

Observe the output for any errors. Check for a success message when the script finishes running.

Troubleshooting

To enable debug mode for an API, add a property called cequenceLogLevel and set the value of the property to debug:

  1. From the Gateway tab, click the + icon next to Properties.
  2. Type cequenceLogLevel for the name.
  3. Type debug for the value.

Note: You can only toggle this variable from the IBM APIC UI.

For issues while running the deploy.sh script, log in to the API Connect CLI with the following command and accept the license.

./apic login --sso --context provider --server $CEQUENCE_IBM_SERVER --apiKey $CEQUENCE_IBM_API_KEY

Auto-Publishing an API to an existing product

  1. Click Edit API.
  2. Click Test > Target Configuration.
  3. Edit the catalog and choose the built-in sandbox or any catalog with deployed global policies.
  4. Click Save Preferences.
  5. Click Target Configuration, then toggle Auto-publish to ON.
    Wait for the page to reload.
  6. If the page does not auto reload after ten seconds, check the Online status.
  7. If the page is still offline, reload the browser tab and navigate back to Test.
Was this article helpful?