APISIX SSL/TLS Configuration Guide

APISIX SSL/TLS Security Architecture

Introduction

SSL/TLS configuration is crucial for securing API traffic in APISIX. This guide covers certificate management, SNI support, and best practices for implementing HTTPS in your API gateway.

Certificate Management

Upload Certificate

curl http://127.0.0.1:9080/apisix/admin/ssl/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "cert": "... certificate content ...",
    "key": "... private key content ...",
    "sni": "*.example.com"
}'

Let's Encrypt Integration

curl http://127.0.0.1:9080/apisix/admin/ssl/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "cert": "... cert ...",
    "key": "... key ...",
    "type": "letsencrypt"
}'

SNI (Server Name Indication) Support

APISIX supports SNI for handling multiple certificates on the same IP address and port.

curl http://127.0.0.1:9080/apisix/admin/ssl/3 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "cert": "... certificate content ...",
    "key": "... private key content ...",
    "snis": ["api.example.com", "*.example.com"]
}'

Note: SNI must be supported by both the client and server for this feature to work.

SSL Protocols and Cipher Suites

Configuration Example

# config.yaml
ssl:
  enable: true
  ssl_protocols: TLSv1.2 TLSv1.3
  ssl_ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
  ssl_session_tickets: false

Security Warning: Avoid using older SSL protocols (SSLv3, TLSv1.0, TLSv1.1) as they have known vulnerabilities.

Mutual TLS (mTLS)

Mutual TLS Authentication Flow

curl http://127.0.0.1:9080/apisix/admin/ssl/4 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "cert": "... server cert ...",
    "key": "... server key ...",
    "client_ca_cert": "... client CA cert ...",
    "verify_client": "require"
}'

Certificate Rotation

Best practices for rotating SSL certificates in APISIX:

Upload new certificate while keeping the old one active
Update routes to use the new certificate
Remove old certificate after grace period

# Example of certificate rotation
# 1. Upload new certificate
curl http://127.0.0.1:9080/apisix/admin/ssl/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "cert": "... new cert ...",
    "key": "... new key ...",
    "sni": "api.example.com"
}'

# 2. Update routes (after verification)
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -d '
{
    "ssl_id": "5"
}'

Best Practices

Security Recommendations

Use TLS 1.2 or higher
Implement proper certificate management
Enable HSTS for HTTPS-only access
Regular certificate rotation
Monitor certificate expiration

Pro Tip: Use automated certificate management tools like cert-manager when running APISIX in Kubernetes.

Troubleshooting

Common Issues

Certificate chain issues
SNI configuration problems
Certificate expiration
Cipher suite mismatches