Custom Certificate Authority

Note:

• The Custom Certificate Authority functionality is available only for licensed users.
• This feature requires a valid license with Custom Certificate Authority access enabled.

​

Overview

​

Architecture

​

Configuration

​

JSON Configuration

{
    "dispatcher": {
        "ca_cert_path": "/path/to/ca-certificate.crt"
    }
}

​

Environment Variables

CONVOY_DISPATCHER_CACERT_PATH="/path/to/ca-certificate.crt"

​

Helm Chart Configuration

global:
  convoy:
    cacert_content: |
      -----BEGIN CERTIFICATE-----
      # Your CA certificate content
      -----END CERTIFICATE-----
    # OR
    cacert_secret_name: "my-ca-cert-secret"

​

Creating Kubernetes Secret

kubectl create secret generic my-ca-cert-secret \
  --from-file=ca.crt=/path/to/your/ca-certificate.crt

​

Certificate Requirements

​

Format

• Content structure: Must be in PEM format with BEGIN/END markers
• Certificate type: CA certificate (not endpoint certificate)

​

Example Certificate Structure

-----BEGIN CERTIFICATE-----
MIIFtzCCA5+gAwIBAgIUIYdQv74LF6tTl3VXgrlOtmP4ISIwDQYJKoZIhvcNAQEL
... (base64 encoded certificate content) ...
-----END CERTIFICATE-----

​

Implementation Details

​

How It Works

1. Certificate Loading: Convoy loads your custom CA certificate during startup
2. Trust Store: The certificate is added to the TLS trust store
3. TLS Verification: All HTTPS connections use the combined trust store
4. Security: Maintains proper certificate validation while supporting custom CAs

​

Component Coverage

• Server: Validates endpoints during creation/update
• Agent: Delivers webhooks to endpoints
• Worker: Processes webhook delivery tasks

​

Troubleshooting

​

Common Issues

​

”x509: certificate signed by unknown authority” Error

1. Check License: Ensure your license includes Custom Certificate Authority feature
2. Verify Configuration: Confirm CA certificate path and format
3. Restart Services: Restart Convoy after adding CA certificate
4. Check Logs: Look for CA certificate loading messages

​

Feature Not Available

• Contact sales to upgrade your license
• Verify license key is properly configured

​

Certificate Format Issues

• Verify certificate is in PEM format
• Check certificate content starts with -----BEGIN CERTIFICATE-----
• Ensure the file is readable by the Convoy process

​

Debug Commands

# Verify certificate format
openssl x509 -in ca-certificate.crt -text -noout

# Check if certificate is properly mounted (Kubernetes)
kubectl exec convoy-server-<pod-id> -- ls -la /etc/convoy/

# Verify environment variable
kubectl exec convoy-server-<pod-id> -- env | grep CONVOY_DISPATCHER_CACERT_PATH

# Check Convoy logs for CA loading
kubectl logs convoy-server-<pod-id> | grep -i "ca\|cert\|tls"

​

Best Practices

​

Security

• Use Kubernetes secrets for certificate storage
• Rotate certificates regularly
• Monitor certificate expiration dates
• Limit access to certificate secrets

​

Configuration

• Use cacert_secret_name for production (more control)
• Use cacert_content for development/testing (easier)
• Document which certificates are trusted
• Version control your configuration

​

Maintenance

• Plan certificate rotation procedures
• Test certificate updates in non-production first
• Keep backup of original certificates
• Monitor for certificate-related errors

​

Related Documentation

• Deployment Guide - General configuration options
• Helm Chart Configuration - Kubernetes deployment
• Best Practices - Security and best practices
• Paid Features - Available premium features