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 enables administrators to govern the full API lifecycle. Its proxy capability acts 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 to discover and protect the APIs that IBM API Connect manages.

To integrate with the Cequence UAP platform, IBM API Connect sends all request and response data to the Cequence UAP platform's traffic ingestion API. This integration is asynchronous and happens outside the request and response path. IBM API Connect's Activity Log captures each transaction, and IBM API Connect's Analytics Offload streams the transaction to the Cequence Bridge's Splunk HEC endpoint. Because delivery happens outside the request and response path, the integration adds no in-line latency to the API call. This integration requires a self-hosted or Reserved Instance IBM API Connect deployment, together with kubectl or oc access to the analytics cluster.

High-level architecture

The following steps describe the API call flow between IBM API Connect and the Cequence UAP platform.

API call flow diagram showing the integration between IBM API Connect and the Cequence UAP platform

  1. IBM API Connect's Activity Log records each API transaction as it passes through the gateway. A content mode, configured for each API, determines whether the log captures metadata and headers only, or metadata, headers, and bodies.
  2. IBM API Connect's Analytics Offload, running on the self-hosted analytics cluster, asynchronously streams each captured event to the Cequence Bridge's Splunk HEC endpoint, using an authorization token. This transmission is independent of, and happens after, the client request and response.
  3. The Cequence Bridge accepts the event and forwards it to the Cequence UAP Edge for threat analysis, detection, and mitigation.
  4. Because capture and delivery both happen outside the request and response path, a slow or unreachable Cequence Bridge does not add latency to, or block, the API call.

Terms used in this article

The following terms have specific meanings in the context of IBM API Connect.

Catalog: 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 partition within a Catalog that enables multiple product teams to manage Products and APIs independently in a single Catalog. A Space behaves like a sub-catalog, except that Products and APIs in all Spaces in a given Catalog are published to the same Developer Portal.

Prerequisites

Verify that the following prerequisites are in place before beginning the installation procedures.

  • A self-hosted or Reserved Instance IBM API Connect deployment.
  • kubectl or oc access to the APIC analytics namespace (apic by default), for the cluster operator applying the offload configuration.
  • IBM APIC CLI V10.
  • The jq filtering utility. Download jq from the project's download page. This link points to an external site that may change or go stale.
  • Cequence UAP platform release 8.7.2 or later.
  • A client ID and client secret generated from the Cequence UAP platform UI.
  • A Cequence Bridge instance, release 6.3.1 or later, deployed close to the customer's IBM API Connect tenant.
  • The Cequence Bridge Splunk HEC endpoint and token.

Detailed prerequisites setup

The following procedures establish several of the prerequisites listed above.

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. Select the Clients tab.
  4. Select 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. Select Save.
    A dialog box with the client secret appears.
  9. Select the copy icon to copy the secret to the clipboard, then select 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 is not displayed again in the UI for security reasons.

Installing IBM APIC CLI V10

The IBM APIC CLI is required to configure Activity Log capture, which cannot be configured through the IBM API Connect UI. The following steps download the toolkit and set up the required directory structure.

  1. From the IBM API Connect dashboard, select Tools For Download.
    Tools For Download option in the IBM API Connect dashboard
  2. Select the link for the operating system of the host where the APIC toolkit runs.

  3. From a terminal, run the following commands to set environments and create the required 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. Copy the toolkit archive downloaded from the IBM dashboard to the $CEQUENCE_APIC_HOME/cli folder.
    • On Linux, copy toolkit-linux.tgz.
    • On macOS, copy toolkit-mac.zip.

  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 created earlier in this article.

Setting up the IBM APIC Cequence .env file

The .env file contains the configuration that connects the plugin to your IBM API Connect environment and the Cequence UAP platform. Verify that all prerequisites are in place 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, from the top-right corner of the dashboard, select the user icon, then select My API Keys, then select Add.
      My API Keys option in the IBM API Connect user menu
    • Copy the API key and note it for later use. In the .env file, set the value of CEQUENCE_IBM_SERVER to the URL that appears after the --server string in the Use API key with APIC CLI field.
      My API Keys page in IBM API Connect showing the Use API key with APIC CLI field
      CEQUENCE_IBM_SERVER value in the .env file
    • Navigate to APIC Settings and set a value for CEQUENCE_IBM_ORGANIZATION. The organization name is a short identifying label for your organization.
    • Set CEQUENCE_HEC_URI and CEQUENCE_HEC_TOKEN to the Cequence Bridge Splunk HEC endpoint and token provided by the Cequence team.

Key attributes in the .env file

The following attributes control plugin behavior and can be adjusted after initial setup.

#############################################################
# Variables specific to your IBM API Connect instance
#############################################################
# API key for an administrator of IBM API Connect.
# Create this value in the IBM API Connect dashboard under My API Keys.
CEQUENCE_IBM_API_KEY="your_api_key"

# Server URL, found under My API Keys in the IBM API Connect dashboard.
CEQUENCE_IBM_SERVER="https://platform-api.us-east-a.apiconnect.automation.ibm.com"

# Name of your organization, found under APIC Settings in the IBM API Connect dashboard.
CEQUENCE_IBM_ORGANIZATION="your_org_name"

# Set to true to deploy to all catalogs and spaces. Set to false to deploy
# only to the catalogs and spaces listed in config.jsonc.
CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES="false"

# Set to true to disable capture. Used by rollback.sh.
CEQUENCE_IBM_DELETE_GLOBAL_POLICIES="false"

# Set to true to skip deploying to the sandbox catalog.
CEQUENCE_SKIP_SANDBOX_CATALOG="false"

#############################################################
# Splunk HEC delivery settings
# The Cequence team provides the Splunk HEC endpoint and token.
#############################################################
CEQUENCE_HEC_URI="https://bridge.org.cequence.ai:8088/services/collector/event"
CEQUENCE_HEC_TOKEN="your_hec_token"

# Capture bodies. false = discovery mode, metadata and headers only.
# true = payload mode, also captures bodies, subject to size limits.
CEQUENCE_HEC_CAPTURE_BODIES="true"

# Deploy a catalog-wide buffering policy automatically. Relevant only when
# CEQUENCE_HEC_CAPTURE_BODIES is "true".
CEQUENCE_HEC_DEPLOY_BUFFER_POLICY="true"

# Capture bodies on error (4xx/5xx) transactions even in discovery mode.
CEQUENCE_HEC_ERROR_BODIES="false"

# Activity Log content mode is configured for each API individually.
# true sets it on every API and republishes the API. false prints the manual
# steps instead.
CEQUENCE_HEC_AUTO_ACTIVITY_LOG="false"

# Optional comma-separated list of API names or IDs to exclude from the offload.
CEQUENCE_HEC_EXCLUDE_APIS=""

#############################################################
# Shared settings
#############################################################
# Maximum request and response body size in bytes. Larger bodies are
# truncated with a marker. Default: 32000.
CEQUENCE_MAX_REQ_BODY_SIZE="32000"
CEQUENCE_MAX_RES_BODY_SIZE="32000"

# Flat sample rate from 0.0 to 1.0, applied to both reads and writes. A value
# of 0.1 captures approximately 10% of non-priority traffic. In most cases,
# use 1.0, since delivery is already outside the request and response path.
CEQUENCE_SAMPLE_RATE="0.1"

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

cp config-template.jsonc config.jsonc

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

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

Logging 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. Run the login command for your 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

Run the following commands to retrieve information about your IBM API Connect environment before deploying.

  1. From the $CEQUENCE_APIC_HOME/cli directory, run the following command to retrieve 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 CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES to the first result from the previous command.

    export CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES=apic-gwv6a-xa3

Deployment configuration

You can apply the Cequence configuration using one of two approaches.

Approach 1: global deployment to all catalogs and spaces

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

Approach 2: deployment to specific catalogs and spaces

  1. In the .env file, set CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES to false.

  2. From the $CEQUENCE_APIC_HOME/scripts directory, create a config.jsonc file from the template.

    cp config-template.jsonc config.jsonc

  3. From the $CEQUENCE_APIC_HOME/cli directory, run the following command to retrieve the list of catalogs.

    ./apic catalogs:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER

  4. To retrieve 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 from Cequence processing

To exclude specific APIs from the offload, set CEQUENCE_HEC_EXCLUDE_APIS in the .env file to a comma-separated list of API names or IDs.

Deploying the Cequence configuration

Run the deployment script from the $CEQUENCE_APIC_HOME/scripts directory. This configures Activity Log capture for the selected catalogs and spaces.

chmod +x *.sh
./deploy.sh

Monitor the output for any errors. When the script finishes running, verify that a success message appears.

Configuring the Cequence Bridge reader

The operator responsible for the Cequence Bridge deployment must configure the Bridge to accept events from the Splunk HEC reader. In the Cequence Bridge's docker-compose file, set the following environment variables.

      - READER_TYPE="splunk-hec"

Configuring Splunk HEC analytics offload

Complete this one-time configuration after running the deployment script. A cluster operator with kubectl or oc access to the APIC analytics namespace must perform this step.

From the $CEQUENCE_APIC_HOME/scripts directory, run the following commands.

cd splunk-hec/offload
./apply-offload.sh apply
./apply-offload.sh verify

This configuration points IBM Analytics Offload to the Cequence Bridge Splunk HEC endpoint.

Testing the plugin setup

Testing the integration

Send a request to any API deployed in a catalog or space where the Activity Log and Analytics Offload configuration is enabled. Verify that IBM API Connect's Activity Log records the transaction, and that Analytics Offload forwards the event to the Cequence Bridge's Splunk HEC endpoint.

Verifying transactions in the Cequence UAP platform

From the Cequence UAP platform, navigate to the transactions view and verify that transactions appear. Verify that request metadata, headers, and payload visibility match the configured capture mode.

Rollback

Use the rollback script to revert the Cequence configuration for the selected deployment scope.

  1. Open $CEQUENCE_APIC_HOME/scripts/.env.
  2. Set CEQUENCE_IBM_DELETE_GLOBAL_POLICIES to true.

  3. Run the rollback script.

    cd $CEQUENCE_APIC_HOME/scripts
./rollback.sh

Monitor the output for any errors. When the script finishes running, verify that the Activity Log and Analytics Offload configuration has been reverted from the intended catalogs and spaces.

Troubleshooting

The following procedures address common issues encountered during and after installation.

Enabling debug mode for an API

To enable debug mode for a specific API, add a property called cequenceLogLevel and set its value to debug. This property can only be toggled from the IBM APIC UI.

  1. From the Gateway tab, select the + icon next to Properties.
  2. Enter cequenceLogLevel as the name.
  3. Enter debug as the value.
  4. Select Add.

Resolving deploy.sh issues

When you encounter issues running the deploy.sh script, log in to the IBM API Connect CLI and accept the license using the following command.

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

Auto-publishing an API to an existing product

  1. Select Edit API.
  2. Navigate to Test Target Configuration.
  3. Edit the catalog and choose the built-in sandbox or any catalog where the Cequence configuration has been deployed.
  4. Select Save Preferences.
  5. From Target Configuration, toggle Auto-publish to ON and wait for the page to reload.
  6. If the page does not reload automatically after ten seconds, check the Online status.
  7. If the status is still offline, reload the browser tab and navigate back to Test.
Was this article helpful?
日本語（日本）