Skip to main content

mTLS Client Certificate

Use mTLS credentials when backends require certificate-based client authentication.

Required material​

  • Client certificate (or chain)
  • Private key
  • Optional passphrase

Setup steps​

  1. Create credential type mTLS Client Certificate.
  2. Upload certificate and key material.
  3. Attach credential to target collection or workflow call.

Certificate material example​

Generate a test client certificate pair:

openssl genrsa -out upstream-client.key 2048
openssl req -new -key upstream-client.key -out upstream-client.csr \
  -subj "/CN=zerq-upstream-client/O=ExampleCorp/C=US"
openssl x509 -req -in upstream-client.csr -CA upstream-ca.crt -CAkey upstream-ca.key \
  -CAcreateserial -out upstream-client.crt -days 365 -sha256

Upload these values into the mTLS credential:

  • client_certificate -> contents of upstream-client.crt
  • client_private_key -> contents of upstream-client.key
  • ca_certificate -> contents of upstream-ca.crt (optional but recommended)

API payload example​

{
  "name": "payments-upstream-mtls",
  "type": "mtls",
  "client_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "client_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "ca_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Env-backed example​

For secret managers or container env injection, use env-backed fields:

  • client_certificate_use_env + client_certificate_env_var
  • client_private_key_use_env + client_private_key_env_var
  • ca_certificate_use_env + ca_certificate_env_var

Troubleshooting encrypted private keys​

If your key file is passphrase-encrypted, outbound calls can fail until you provide a usable PEM key.

# Convert encrypted key to unencrypted PEM for runtime use
openssl pkey -in upstream-client.encrypted.key -out upstream-client.key

If you receive a combined PEM bundle, split cert/key first, then convert the key:

awk '/-----BEGIN ENCRYPTED PRIVATE KEY-----/,/-----END ENCRYPTED PRIVATE KEY-----/' bundle.pem > encrypted.key
awk '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/' bundle.pem > upstream-client.crt
openssl pkey -in encrypted.key -out upstream-client.key

Practical guidance​

  • Track certificate expiration and renew before cutoff.
  • Restrict private key access to platform operators only.
  • Validate full trust chain in non-production first.