IBM DataPower TLS Client Profile Configuration via CLI

Note: This article is based on the earlier draft 2026-03-10-datapower-tls-client-profile-cli.md with expanded content and v12 updates.

TLS client profiles in IBM DataPower define how the gateway authenticates to backend services. Whether you’re connecting to a payment processor, a database, or an upstream microservice, the TLS client profile is the configuration that controls the mTLS handshake from DataPower to your backend. Configuring this through the web UI is fine for one-off configurations, but when you’re managing multiple environments or need to automate deployments, the CLI is the right tool.

This article covers the DataPower CLI commands for configuring TLS client profiles, common errors and how to fix them, and how to script bulk TLS profile operations.

What Is a TLS Client Profile?
Prerequisites
DataPower CLI Basics
Creating a TLS Client Profile via CLI
Importing Certificates and Keys
Associating the Profile with a Backend
Common Errors and Troubleshooting
Scripting Bulk Operations

What Is a TLS Client Profile?

A TLS Client Profile is a DataPower configuration object that defines:

The client certificate DataPower presents to the backend service (for mTLS)
The CA certificates DataPower trusts from the backend (server certificate validation)
The TLS version and cipher suite settings
CRL (Certificate Revocation List) settings for certificate validation

When DataPower acts as a client to your backend service (in a proxy or fetch operation), it uses the TLS client profile to determine how to authenticate and what to trust.

Prerequisites

DataPower firmware 10.x or later
Access to the DataPower CLI (via SSH or console)
Admin credentials or the xml-mgmt role
Certificates ready in PEM format

DataPower CLI Basics

Connecting to DataPower CLI

# SSH to DataPower
ssh admin@datapower.example.com

# Or use the SOMA/XML management interface via curl
# (useful for automation when SSH is not available)
curl -X POST \
  --data @request.xml \
  https://datapower.example.com:5550/service/mgmt/2.0

Key CLI Conventions

show commands display current configuration
conf mode is where you enter configuration changes
switch navigates between domains
Objects are created with name and configuration mode

Navigating to the Right Context

# List domains
show domains

# Switch to a specific domain
switch domain apic-gateway

# Navigate to TLS client profile configuration
config
# Now in config mode:
tls-client-profile

Creating a TLS Client Profile via CLI

Step 1: Navigate to the Profile Context

# From config mode:
tls-client-profile

Step 2: Create the Profile

# Create a new TLS client profile
apic-datapower# create MyBackendTLSProfile
apic-datapower# info

# Set the profile parameters
apic-datapower# set identity-preferred-ciphers none
apic-datapower# set cipher-type all
apic-datapower# set cipher-negotiation dynamic
apic-datapower# set tls-options true
apic-datapower# set tls-version TLS_v1.2+
apic-datapower# set ssl-options true
apic-datapower# set forward-proxy-bi-directional false
apic-datapower# set pre-shared-key-list []

Step 3: Set the Client Certificate

apic-datapower# set client-certificate MyClientCert
apic-datapower# set client-key MyClientKey

Step 4: Set the Trusted CA List

apic-datapower# set validate-server-cert true
apic-datapower# set ca-cert-reference TrustedBackendCAs

Step 5: Enable CRL Checking (Optional but Recommended)

apic-datapower# set revocation-check true
apic-datapower# set crl-entry-caching true
apic-datapower# set crl-cache-timeout 3600

Step 6: Save and Exit

apic-datapower# save
apic-datapower# exit

Complete TLS Client Profile Configuration

# Full sequence in one session
ssh admin@datapower.example.com << 'EOF'
switch domain apic-gateway
config
tls-client-profile
create PaymentsBackendTLS
set description "TLS profile for payment processor backend"
set tls-version TLS_v1.2+
set cipher-type all
set validate-server-cert true
set ca-cert-reference PaymentProcessorCAs
set client-certificate apic-client-cert
set client-key apic-client-key
set revocation-check true
set forward-proxy-bi-directional false
save
exit
EOF

Importing Certificates and Keys

Before creating the TLS client profile, you need to import the certificates into DataPower’s certificate store.

Import a Client Certificate with Key

# In config mode:
crypto
certificate
create MyClientCert
set literal "
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiUMA0GCSqGSIb3D...
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...
-----END PRIVATE KEY-----
"
set format pem
set password ""
save
exit

Import a CA Certificate (Trusted CA)

crypto
ca-certificate
create PaymentProcessorCAs
set literal "
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiUMA0GCSqGSIb3D...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiUMB...
-----END CERTIFICATE-----
"
set format pem
save
exit

Import via SOMA/curl (Useful for Scripting)

# Upload a certificate to DataPower via the management interface
curl -k -u admin:password \
  -X POST \
  -H "Content-Type: application/soap+xml" \
  -d @upload-cert-request.xml \
  https://datapower.example.com:5550/service/mgmt/2.0

Where upload-cert-request.xml contains:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <dp:request xmlns:dp="http://www.datapower.com/management">
      <dp:do-action>CertMgmtRequest</dp:do-action>
      <CertFile format="pem" name="MyClientCert">
$(cat my-client-cert.pem)
</CertFile>
    </dp:request>
  </soap:Body>
</soap:Envelope>

Associating the Profile with a Backend

A TLS client profile on its own does nothing — it must be referenced by a backend service (a remote-proxy or http-handler).

In a HTTP Handler Configuration

# In config mode:
http-handler
create my-payment-backend
set remote-host payments-api.example.com
set remote-port 443
set tls-client-profile PaymentsBackendTLS
set ssl-options true
set url RewriteRule
set timeout 30
save
exit

In an API Gateway Assembly (v12 API Gateway)

For the v12 API Gateway, the TLS client profile is referenced via the gateway configuration, not in the assembly:

# Set TLS client profile for a backend URL
apic backend-urls:update \
  --backend-id my-backend-id \
  --tls-client-profile PaymentsBackendTLS

Common Errors and Troubleshooting

Error: `SSLHandshakeException: No trusted CA found`

Cause: DataPower doesn’t have the backend’s server certificate (or its issuing CA) in its trusted CA store. Fix: Import the backend’s server certificate or its issuing CA into a CA certificate object and reference it in the TLS client profile’s ca-cert-reference.

Error: `SSLHandshakeException: Certificate verify failed`

Cause: Server certificate validation failed — either the certificate is expired, has a SAN mismatch, or the chain is incomplete. Fix: Check the certificate validity, SAN entries, and ensure the full certificate chain (server cert + intermediates + root) is in the CA certificate object.

Error: `Client certificate not found`

Cause: The client-certificate in the TLS client profile doesn’t exist in the DataPower certificate store. Fix: Verify the certificate name exactly matches what’s in show crypto certificate. Names are case-sensitive.

Error: `TLS version mismatch`

Cause: DataPower and the backend can’t agree on a TLS version. Common when the backend only supports TLS 1.0/1.1 and DataPower is configured for TLS 1.2+. Fix: Adjust tls-version on the TLS client profile. Set tls-version TLS_v1.0+ if the backend requires older TLS versions (and consider upgrading the backend).

# Relax TLS version to allow TLS 1.0 (if required by legacy backend)
set tls-version TLS_v1.0+

Error: `Cipher suite mismatch`

Cause: No common cipher suites between DataPower and the backend. Fix: Set cipher-type all to allow DataPower to negotiate any available cipher. For debugging, enable cipher debug logging:

# Enable cipher debugging
debug-mode
logging
set debug-mode true
set cip
``` exit

Debugging TLS Connections

# Show current TLS client profile configuration
show tls-client-profile MyBackendTLSProfile

# Test TLS connectivity (if available in your DataPower firmware)
test crypto tls-handshake MyBackendTLSProfile host payments-api.example.com port 443

# View TLS-related logs
show log temp | grep -i "tls\|ssl\|certificate"

Scripting Bulk Operations

When you have many TLS client profiles to create (e.g., one per backend service), script the creation rather than doing it manually.

Script: Create Multiple TLS Client Profiles

#!/usr/bin/env bash
# create-tls-profiles.sh — bulk create TLS client profiles on DataPower
# Usage: ./create-tls-profiles.sh config.csv

set -e

DP_HOST="${DATAPOWER_HOST:-datapower.example.com}"
DP_USER="${DATAPOWER_USER:-admin}"
DP_PASS="${DATAPOWER_PASS:-}"

# CSV format: profile_name,description,client_cert,ca_certs,remote_host
while IFS=, read -r name desc client_cert ca_certs remote_host; do
  echo "Creating TLS client profile: $name"
  
  sshpass -p "$DP_PASS" ssh -o StrictHostKeyChecking=no "$DP_USER@$DP_HOST" << EOF
switch domain apic-gateway
config
tls-client-profile
create $name
set description "$desc"
set tls-version TLS_v1.2+
set cipher-type all
set validate-server-cert true
set ca-cert-reference $ca_certs
set client-certificate $client_cert
set client-key ${client_cert}-key
set revocation-check false
save
exit
EOF
  echo "Done: $name"
done < "$1"

Note: The script uses sshpass for non-interactive SSH. In production, use SSH keys instead of password-based authentication.

Script: Export Current TLS Profile Configuration

#!/usr/bin/env bash
# export-tls-profiles.sh — export all TLS client profiles to JSON
# Useful for backup and migration

DP_HOST="${DATAPOWER_HOST:-datapower.example.com}"
DP_USER="${DATAPOWER_USER:-admin}"
DP_PASS="${DATAPOWER_PASS:-}"

OUTPUT_FILE="${1:-tls-profiles-export.json}"

sshpass -p "$DP_PASS" ssh -o StrictHostKeyChecking=no "$DP_USER@$DP_HOST" << 'EOF' > "$OUTPUT_FILE"
switch domain apic-gateway
config
tls-client-profile
show
EOF

echo "Exported to $OUTPUT_FILE"

Summary

Configuring TLS client profiles via CLI on DataPower is a practical skill for any API Connect operator. The key commands are straightforward: import certificates first, create the TLS client profile, configure the cipher and TLS version settings, then associate the profile with your backend service.

The most common issues are certificate chain problems (missing CAs), TLS version mismatches with legacy backends, and client certificate reference errors. When in doubt, show commands are your friend — they reveal the exact state of the configuration.

For bulk operations, scripting via SSH with a tool like sshpass or expect is far more practical than manual configuration. Always test TLS configuration changes in a non-production domain first.

Questions about DataPower TLS configuration? Find me on Twitter @cminion.

ABOUT	APICONNECT	API	DATAPOWER	OPENSHIFT	EVENTSTREAMS	INTEGRATION	DAY2-OPS	ACE
*All opinions expressed here are very much my own or of the author of the article, not those of IBM. All Code provided is provide as is with no support unless otherwise stated.*

Table of Contents