Implementing mTLS-Protected REST API Endpoints in AWS API Gateway: A Comprehensive Guide

In today's security-first world, protecting your APIs goes beyond traditional authentication methods. Mutual TLS (mTLS) provides an additional layer of security by ensuring both the client and server authenticate each other during the TLS handshake. This comprehensive guide walks you through implementing a REST API endpoint protected by mTLS in AWS API Gateway, complete with a practical Python 3.12 example.

Understanding Mutual TLS (mTLS)

What is mTLS?

Mutual TLS (mTLS) is an authentication method that extends the standard TLS protocol to require authentication from both parties in a connection. Unlike regular TLS where only the server presents a certificate, mTLS requires both the client and server to present valid certificates and verify each other's identity.

How mTLS Works

The mTLS handshake process involves these key steps:

1. Client connects to server

2. Server presents its TLS certificate

3. Client verifies the server's certificate

4. Client presents its TLS certificate (additional step for mTLS)

5. Server verifies the client's certificate (additional step for mTLS)

6. Server grants access

7. Client and server exchange information over encrypted TLS connection

Benefits of mTLS

mTLS provides protection against various security threats:

• On-path attacks: Attackers cannot intercept communications without valid certificates

• Spoofing attacks: Both parties must authenticate with legitimate certificates

• Credential stuffing: Stolen credentials alone are insufficient without valid certificates

• Brute force attacks: Password-based attacks are mitigated by certificate requirements

• Malicious API requests: Ensures API requests come from legitimate, authenticated clients only

Prerequisites for AWS API Gateway mTLS

Before implementing mTLS in AWS API Gateway, ensure you have:

1. Regional Custom Domain Name

mTLS requires a Regional custom domain name for your API. You cannot use the default execute-api endpoint with mTLS.

2. SSL/TLS Certificate

You need at least one certificate configured in AWS Certificate Manager (ACM) for your custom domain name. This can be:

• A publicly trusted certificate from ACM

• An imported certificate

• A certificate from AWS Private Certificate Authority

3. Truststore Configuration

Create a truststore containing X.509 certificates from trusted Certificate Authorities. The truststore must:

• Include the complete chain of trust (issuing CA to root CA)

• Support certificates with maximum chain length of four

• Use supported algorithms (SHA-256+, RSA-2048+, ECDSA-256/384)

• Be stored as a .pem file in Amazon S3

AWS API Gateway mTLS Configuration Guide

Before implementing the Python application, let's walk through the complete AWS API Gateway mTLS setup process.

Step 1: Prerequisites Setup

1.1 Create an S3 Bucket for Truststore

First, create an S3 bucket to store your truststore:

# Create S3 bucket for truststore
aws s3 mb s3://my-mtls-truststore-bucket --region us-east-1

# Enable versioning for truststore management
aws s3api put-bucket-versioning \
    --bucket my-mtls-truststore-bucket \
    --versioning-configuration Status=Enabled

1.2 Set Up AWS Certificate Manager (ACM)

You have two options for server certificates:

Option A: Request a public certificate from ACM

# Request a certificate for your domain
aws acm request-certificate \
    --domain-name api.mycompany.com \
    --validation-method DNS \
    --region us-east-1

Option B: Import an existing certificate

# Import your own certificate
aws acm import-certificate \
    --certificate fileb://server-cert.pem \
    --private-key fileb://server-key.pem \
    --certificate-chain fileb://cert-chain.pem \
    --region us-east-1

Step 2: Create and Configure the Truststore

2.1 Create Certificate Authority (CA) Structure

For development/testing, create your own CA:

# Create CA private key
openssl genrsa -out ca-private-key.pem 4096

# Create CA certificate
openssl req -new -x509 -key ca-private-key.pem -out ca-certificate.pem -days 365 \
    -subj "/C=US/ST=California/L=San Francisco/O=MyCompany/OU=IT/CN=MyCompany Root CA"

# Create intermediate CA (optional but recommended)
openssl genrsa -out intermediate-ca-key.pem 4096
openssl req -new -key intermediate-ca-key.pem -out intermediate-ca-csr.pem \
    -subj "/C=US/ST=California/L=San Francisco/O=MyCompany/OU=IT/CN=MyCompany Intermediate CA"

# Sign intermediate CA with root CA
openssl x509 -req -in intermediate-ca-csr.pem -CA ca-certificate.pem \
    -CAkey ca-private-key.pem -CAcreateserial -out intermediate-ca-cert.pem -days 365

2.2 Create the Truststore File

The truststore must include the complete certificate chain:

# Create truststore file (certificates.pem)
cat > certificates.pem << 'EOF'
-----BEGIN CERTIFICATE-----
<Intermediate CA Certificate Contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Root CA Certificate Contents>
-----END CERTIFICATE-----
EOF

# Alternative: Combine certificate files
cat intermediate-ca-cert.pem ca-certificate.pem > certificates.pem

2.3 Validate Truststore Format

Ensure your truststore meets AWS requirements:

# Check certificate format and validity
openssl x509 -in certificates.pem -text -noout

# Verify the certificate chain
openssl verify -CAfile certificates.pem certificates.pem

Important Requirements:

• Maximum chain length: 4 certificates

• Supported algorithms: SHA-256+, RSA-2048+, ECDSA-256/384

• Format: PEM with proper BEGIN/END certificate markers

• Complete chain from issuing CA to root CA

2.4 Upload Truststore to S3

# Upload truststore to S3
aws s3 cp certificates.pem s3://my-mtls-truststore-bucket/truststore/certificates.pem

# Verify upload and get version ID
aws s3api list-object-versions \
    --bucket my-mtls-truststore-bucket \
    --prefix truststore/certificates.pem

Step 3: Configure Custom Domain with mTLS

3.1 Create Custom Domain Name

Create a Regional custom domain with mTLS enabled:

# Create custom domain with mTLS
aws apigateway create-domain-name \
    --region us-east-1 \
    --domain-name api.mycompany.com \
    --regional-certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456789012 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://my-mtls-truststore-bucket/truststore/certificates.pem

Important Notes:

• Use REGIONAL endpoint configuration (mTLS not supported for EDGE)

• Security policy must be TLS_1_2

• Mutual TLS is not supported for private APIs

3.2 Configure DNS and Base Path Mapping

Get the API Gateway domain name for DNS configuration:

# Get domain name details
aws apigateway get-domain-name --domain-name api.mycompany.com

# Sample response includes distributionDomainName for DNS
{
    "domainName": "api.mycompany.com",
    "distributionDomainName": "d123456789.execute-api.us-east-1.amazonaws.com",
    "regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456789012",
    "mutualTlsAuthentication": {
        "truststoreUri": "s3://my-mtls-truststore-bucket/truststore/certificates.pem",
        "truststoreVersion": "abc123def456"
    }
}

Create DNS CNAME record pointing to the distributionDomainName.

3.3 Create Base Path Mapping

Connect your custom domain to your API:

# Create base path mapping
aws apigateway create-base-path-mapping \
    --domain-name api.mycompany.com \
    --rest-api-id your-rest-api-id \
    --stage prod \
    --base-path ""  # Empty for root path

Step 4: Disable Default Execute-API Endpoint

Critical Security Step: Disable the default endpoint to force mTLS:

# Disable default endpoint
aws apigateway update-rest-api \
    --rest-api-id your-rest-api-id \
    --patch-operations op=replace,path=/disableExecuteApiEndpoint,value=true

Step 5: Create and Manage Client Certificates

5.1 Generate Client Certificates

Create client certificates for testing:

# Create client private key
openssl genrsa -out client-private-key.pem 4096

# Create client certificate signing request
openssl req -new -key client-private-key.pem -out client-csr.pem \
    -subj "/C=US/ST=California/L=San Francisco/O=acme-corp.com/OU=Engineering/CN=John Doe/[email protected]"

# Sign client certificate with your CA
openssl x509 -req -in client-csr.pem \
    -CA intermediate-ca-cert.pem -CAkey intermediate-ca-key.pem \
    -CAcreateserial -out client-certificate.pem -days 365

# Create client certificate bundle (certificate + chain)
cat client-certificate.pem intermediate-ca-cert.pem > client-cert-bundle.pem

5.2 Validate Client Certificate

# Verify client certificate against truststore
openssl verify -CAfile certificates.pem client-certificate.pem

# Check certificate details
openssl x509 -in client-certificate.pem -text -noout | grep -E "(Subject|Issuer|Validity)"

Step 6: API Gateway Certificate Validation

AWS API Gateway validates these certificate properties:

Property	Validation
X.509 Syntax	Must meet X.509 syntax requirements
Integrity	Content must not be altered from CA signature
Validity	Certificate must be within validity period
Chain of Trust	Complete unbroken chain (max 4 certificates)
Algorithm Support	SHA-256+, RSA-2048+, ECDSA-256/384

Note: API Gateway does NOT verify certificate revocation status (CRL/OCSP).

Step 7: Update Truststore (Production Management)

7.1 Upload New Truststore Version

# Upload updated truststore
aws s3 cp updated-certificates.pem s3://my-mtls-truststore-bucket/truststore/certificates.pem

# Get new version ID
NEW_VERSION=$(aws s3api list-object-versions \
    --bucket my-mtls-truststore-bucket \
    --prefix truststore/certificates.pem \
    --query 'Versions[0].VersionId' --output text)

7.2 Update Domain Configuration

# Update domain to use new truststore version
aws apigateway update-domain-name \
    --domain-name api.mycompany.com \
    --patch-operations op=replace,path=/mutualTlsAuthentication/truststoreVersion,value=$NEW_VERSION

Step 8: Monitoring and Validation

8.1 Test mTLS Configuration

# Test with valid client certificate
curl -v --key client-private-key.pem --cert client-cert-bundle.pem \
    https://api.mycompany.com/health

# Test without certificate (should fail)
curl -v https://api.mycompany.com/health

# Test with invalid certificate (should fail)
curl -v --key invalid-key.pem --cert invalid-cert.pem \
    https://api.mycompany.com/health

8.2 Check Certificate Warnings

# Get domain status and warnings
aws apigateway get-domain-name --domain-name api.mycompany.com

# Check for certificate warnings in response
{
    "mutualTlsAuthentication": {
        "truststoreWarnings": [
            "Certificate with subject 'CN=Invalid Cert' is expired"
        ]
    }
}

Step-by-Step Python Application Implementation

Step 9: Create the Python API Application

Let's create a secure Python API using FastAPI that will be deployed behind our mTLS-protected API Gateway:

Project Structure

mtls-secure-api/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── models.py
│   ├── auth.py
│   └── utils.py
├── requirements.txt
├── Dockerfile
└── serverless.yml

requirements.txt

fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0
python-jose[cryptography]==3.3.0
cryptography==41.0.8
mangum==0.17.0
boto3==1.34.0

app/models.py

from pydantic import BaseModel, Field
from typing import Optional, Dict, Any
from datetime import datetime

class UserProfile(BaseModel):
    user_id: str = Field(..., description="Unique user identifier")
    email: str = Field(..., description="User email address")
    name: str = Field(..., description="Full name")
    organization: str = Field(..., description="User's organization")
    created_at: datetime = Field(default_factory=datetime.utcnow)

class APIResponse(BaseModel):
    success: bool
    message: str
    data: Optional[Dict[str, Any]] = None
    timestamp: datetime = Field(default_factory=datetime.utcnow)

class SecureDataRequest(BaseModel):
    data_type: str = Field(..., description="Type of secure data requested")
    parameters: Optional[Dict[str, Any]] = None

class SecureDataResponse(BaseModel):
    data_type: str
    secure_data: Dict[str, Any]
    access_level: str
    generated_at: datetime = Field(default_factory=datetime.utcnow)

app/auth.py

import json
import base64
from typing import Optional, Dict, Any
from fastapi import HTTPException, status
from jose import jwt, JWTError

class mTLSAuthenticator:
    """Handle mTLS certificate-based authentication"""
    
    def __init__(self):
        self.trusted_organizations = {
            "acme-corp.com": "enterprise",
            "trusted-partner.com": "partner",
            "internal.mycompany.com": "internal"
        }
    
    def extract_cert_info(self, event: Dict[str, Any]) -> Optional[Dict[str, str]]:
        """Extract certificate information from API Gateway event"""
        try:
            # API Gateway forwards client certificate information
            client_cert = event.get("requestContext", {}).get("identity", {}).get("clientCert", {})
            
            if not client_cert:
                return None
            
            cert_info = {
                "subject": client_cert.get("subjectDN", ""),
                "issuer": client_cert.get("issuerDN", ""),
                "serial": client_cert.get("serialNumber", ""),
                "validity": {
                    "not_before": client_cert.get("validity", {}).get("notBefore", ""),
                    "not_after": client_cert.get("validity", {}).get("notAfter", "")
                }
            }
            
            return cert_info
            
        except Exception as e:
            print(f"Error extracting certificate info: {e}")
            return None
    
    def validate_certificate(self, cert_info: Dict[str, str]) -> Dict[str, Any]:
        """Validate certificate and extract user information"""
        if not cert_info:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="No valid client certificate provided"
            )
        
        subject = cert_info.get("subject", "")
        
        # Extract organization from certificate subject
        org = None
        for part in subject.split(","):
            if "O=" in part:
                org = part.split("O=")[1].strip()
                break
        
        if not org or org not in self.trusted_organizations:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Certificate from untrusted organization"
            )
        
        # Extract user information from certificate
        user_info = self._parse_certificate_subject(subject)
        user_info["access_level"] = self.trusted_organizations[org]
        user_info["certificate_serial"] = cert_info.get("serial", "")
        
        return user_info
    
    def _parse_certificate_subject(self, subject: str) -> Dict[str, str]:
        """Parse certificate subject to extract user information"""
        info = {}
        
        parts = subject.split(",")
        for part in parts:
            part = part.strip()
            if "CN=" in part:
                info["common_name"] = part.split("CN=")[1]
            elif "emailAddress=" in part:
                info["email"] = part.split("emailAddress=")[1]
            elif "OU=" in part:
                info["organizational_unit"] = part.split("OU=")[1]
            elif "O=" in part:
                info["organization"] = part.split("O=")[1]
        
        return info

# Global authenticator instance
mtls_auth = mTLSAuthenticator()

app/utils.py

import secrets
import string
from typing import Dict, Any, List
from datetime import datetime, timedelta

def generate_secure_data(data_type: str, access_level: str) -> Dict[str, Any]:
    """Generate secure data based on user's access level"""
    
    base_data = {
        "request_id": generate_request_id(),
        "generated_at": datetime.utcnow().isoformat(),
        "data_classification": get_data_classification(access_level)
    }
    
    if data_type == "financial":
        return {
            **base_data,
            "account_summary": generate_financial_data(access_level),
            "risk_metrics": calculate_risk_metrics(access_level)
        }
    
    elif data_type == "operational":
        return {
            **base_data,
            "system_metrics": generate_operational_data(access_level),
            "performance_indicators": get_performance_kpis(access_level)
        }
    
    elif data_type == "compliance":
        return {
            **base_data,
            "audit_logs": generate_audit_data(access_level),
            "compliance_status": get_compliance_metrics(access_level)
        }
    
    else:
        return {
            **base_data,
            "generic_data": f"Secure data for {data_type}",
            "access_restrictions": get_access_restrictions(access_level)
        }

def generate_request_id() -> str:
    """Generate a unique request ID"""
    return ''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(16))

def get_data_classification(access_level: str) -> str:
    """Get data classification based on access level"""
    classifications = {
        "enterprise": "CONFIDENTIAL",
        "partner": "RESTRICTED",
        "internal": "INTERNAL"
    }
    return classifications.get(access_level, "PUBLIC")

def generate_financial_data(access_level: str) -> Dict[str, Any]:
    """Generate financial data based on access level"""
    if access_level == "enterprise":
        return {
            "total_revenue": 15750000.50,
            "quarterly_growth": 12.5,
            "profit_margin": 23.8,
            "detailed_breakdown": True
        }
    elif access_level == "partner":
        return {
            "revenue_range": "10M-20M",
            "growth_trend": "positive",
            "market_position": "strong"
        }
    else:
        return {
            "public_revenue": "Available in annual report",
            "growth_indicator": "stable"
        }

def generate_operational_data(access_level: str) -> Dict[str, Any]:
    """Generate operational metrics based on access level"""
    base_metrics = {
        "system_uptime": "99.9%",
        "response_time": "45ms",
        "active_users": 1250
    }
    
    if access_level == "enterprise":
        base_metrics.update({
            "detailed_performance": {
                "cpu_utilization": 65.2,
                "memory_usage": 78.5,
                "disk_io": 125.6,
                "network_throughput": 850.3
            },
            "error_rates": {
                "4xx_errors": 0.02,
                "5xx_errors": 0.001
            }
        })
    
    return base_metrics

def calculate_risk_metrics(access_level: str) -> Dict[str, Any]:
    """Calculate risk metrics based on access level"""
    if access_level in ["enterprise", "internal"]:
        return {
            "overall_risk_score": 2.3,
            "security_incidents": 0,
            "compliance_score": 98.5,
            "risk_factors": [
                {"type": "operational", "score": 1.2},
                {"type": "financial", "score": 0.8},
                {"type": "technical", "score": 0.3}
            ]
        }
    else:
        return {
            "risk_category": "low",
            "last_assessment": "2024-01-15"
        }

def generate_audit_data(access_level: str) -> List[Dict[str, Any]]:
    """Generate audit log data based on access level"""
    if access_level == "enterprise":
        return [
            {
                "timestamp": "2024-01-20T10:30:00Z",
                "action": "API_ACCESS",
                "user": "system.audit",
                "resource": "financial_data",
                "result": "SUCCESS"
            },
            {
                "timestamp": "2024-01-20T09:15:00Z",
                "action": "DATA_EXPORT",
                "user": "admin.user",
                "resource": "compliance_report",
                "result": "SUCCESS"
            }
        ]
    else:
        return [
            {
                "timestamp": "2024-01-20T10:30:00Z",
                "action": "API_ACCESS",
                "result": "SUCCESS"
            }
        ]

def get_compliance_metrics(access_level: str) -> Dict[str, Any]:
    """Get compliance metrics based on access level"""
    return {
        "sox_compliance": "COMPLIANT" if access_level == "enterprise" else "N/A",
        "gdpr_status": "COMPLIANT",
        "iso27001": "CERTIFIED" if access_level in ["enterprise", "internal"] else "PENDING",
        "last_audit": "2024-01-15"
    }

def get_performance_kpis(access_level: str) -> Dict[str, Any]:
    """Get performance KPIs based on access level"""
    return {
        "availability": 99.95,
        "throughput": "1000 req/min",
        "latency_p95": "125ms",
        "error_rate": 0.01
    }

def get_access_restrictions(access_level: str) -> List[str]:
    """Get access restrictions based on level"""
    restrictions = {
        "enterprise": [],
        "partner": ["no_export", "time_limited"],
        "internal": ["internal_use_only"]
    }
    return restrictions.get(access_level, ["restricted_access"])

app/main.py

from fastapi import FastAPI, HTTPException, Depends, Request, status
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from mangum import Mangum
import json
from typing import Dict, Any

from .models import APIResponse, SecureDataRequest, SecureDataResponse, UserProfile
from .auth import mtls_auth
from .utils import generate_secure_data, generate_request_id

# Initialize FastAPI application
app = FastAPI(
    title="mTLS Secure API",
    description="A secure API protected by mutual TLS authentication",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc"
)

# Add CORS middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://api.mycompany.com"],  # Your custom domain
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

# Global variables to store request context
_current_request_context = {}

@app.middleware("http")
async def extract_api_gateway_context(request: Request, call_next):
    """Extract API Gateway context from request"""
    global _current_request_context
    
    # For Lambda/API Gateway, the event context is available through request state
    if hasattr(request.state, 'aws_event'):
        _current_request_context = request.state.aws_event
    
    response = await call_next(request)
    return response

def get_user_from_certificate() -> Dict[str, Any]:
    """Extract and validate user information from mTLS certificate"""
    global _current_request_context
    
    # Extract certificate information from API Gateway event
    cert_info = mtls_auth.extract_cert_info(_current_request_context)
    
    # Validate certificate and get user info
    user_info = mtls_auth.validate_certificate(cert_info)
    
    return user_info

@app.get("/health", response_model=APIResponse)
async def health_check():
    """Health check endpoint - no authentication required"""
    return APIResponse(
        success=True,
        message="mTLS Secure API is healthy",
        data={
            "service": "mtls-secure-api",
            "version": "1.0.0",
            "status": "operational"
        }
    )

@app.get("/profile", response_model=UserProfile)
async def get_user_profile(user_info: Dict[str, Any] = Depends(get_user_from_certificate)):
    """Get user profile based on mTLS certificate"""
    try:
        profile = UserProfile(
            user_id=user_info.get("certificate_serial", "unknown"),
            email=user_info.get("email", "[email protected]"),
            name=user_info.get("common_name", "Unknown User"),
            organization=user_info.get("organization", "Unknown Org")
        )
        
        return profile
        
    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Error retrieving user profile: {str(e)}"
        )

@app.post("/secure-data", response_model=SecureDataResponse)
async def get_secure_data(
    request: SecureDataRequest,
    user_info: Dict[str, Any] = Depends(get_user_from_certificate)
):
    """Get secure data based on user's certificate and access level"""
    try:
        access_level = user_info.get("access_level", "internal")
        
        # Generate secure data based on request and access level
        secure_data = generate_secure_data(request.data_type, access_level)
        
        response = SecureDataResponse(
            data_type=request.data_type,
            secure_data=secure_data,
            access_level=access_level
        )
        
        return response
        
    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Error generating secure data: {str(e)}"
        )

@app.get("/certificates/info")
async def get_certificate_info(user_info: Dict[str, Any] = Depends(get_user_from_certificate)):
    """Get information about the client certificate used for authentication"""
    global _current_request_context
    
    cert_info = mtls_auth.extract_cert_info(_current_request_context)
    
    return APIResponse(
        success=True,
        message="Certificate information retrieved successfully",
        data={
            "certificate_details": cert_info,
            "user_info": user_info,
            "authentication_method": "mutual_tls",
            "security_level": "high"
        }
    )

@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    """Custom exception handler for HTTP exceptions"""
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "message": exc.detail,
            "error_code": exc.status_code,
            "request_id": generate_request_id()
        }
    )

@app.exception_handler(Exception)
async def general_exception_handler(request: Request, exc: Exception):
    """General exception handler for unexpected errors"""
    return JSONResponse(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        content={
            "success": False,
            "message": "Internal server error",
            "error_code": 500,
            "request_id": generate_request_id()
        }
    )

# Lambda handler for AWS deployment
def lambda_handler(event, context):
    """AWS Lambda handler function"""
    global _current_request_context
    _current_request_context = event
    
    asgi_handler = Mangum(app)
    return asgi_handler(event, context)

# For local development
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Step 4: Deployment Configuration

Dockerfile

FROM python:3.12-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY app/ ./app/

# Expose port for local development
EXPOSE 8000

# Command for local development
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

serverless.yml (for Serverless Framework deployment)

service: mtls-secure-api

frameworkVersion: '3'

provider:
  name: aws
  runtime: python3.12
  region: us-east-1
  stage: ${opt:stage, 'dev'}
  
  environment:
    STAGE: ${self:provider.stage}
    
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - logs:CreateLogGroup
            - logs:CreateLogStream
            - logs:PutLogEvents
          Resource: 
            - 'arn:aws:logs:${self:provider.region}:*:log-group:/aws/lambda/*:*:*'

functions:
  api:
    handler: app.main.lambda_handler
    timeout: 30
    events:
      - http:
          path: /{proxy+}
          method: ANY
          cors: true
      - http:
          path: /
          method: ANY
          cors: true

plugins:
  - serverless-python-requirements

custom:
  pythonRequirements:
    dockerizePip: true
    dockerSsh: true

Step 5: DNS Configuration and Base Path Mapping

Configure DNS to point to your API Gateway domain:

# Get the domain name from API Gateway
aws apigateway get-domain-name --domain-name api.mycompany.com

# Create a CNAME record in your DNS provider pointing to the API Gateway domain
# Example: api.mycompany.com CNAME d123456789.execute-api.us-east-1.amazonaws.com

Create base path mapping:

aws apigateway create-base-path-mapping \
    --domain-name api.mycompany.com \
    --rest-api-id your-api-id \
    --stage prod

Step 10: AWS-Specific Troubleshooting and Management

Certificate Management in Production

Ownership Verification Certificate (for imported certificates): If using imported certificates or AWS Private CA, you need an ownership verification certificate:

# Request ownership verification certificate
aws acm request-certificate \
    --domain-name api.mycompany.com \
    --validation-method DNS \
    --region us-east-1

# Use this ARN as ownershipVerificationCertificateArn when creating domain with imported cert
aws apigateway create-domain-name \
    --domain-name api.mycompany.com \
    --regional-certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/imported-cert-id \
    --ownership-verification-certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/ownership-cert-id \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://my-mtls-truststore-bucket/truststore/certificates.pem

Disable mTLS

To disable mTLS while keeping the custom domain:

aws apigateway update-domain-name \
    --domain-name api.mycompany.com \
    --patch-operations op=replace,path=/mutualTlsAuthentication/truststoreUri,value=''

Common Domain Status Messages

Monitor your domain status for these conditions:

• PENDING_CERTIFICATE_REIMPORT: Certificate validation failed after reimport

• PENDING_OWNERSHIP_VERIFICATION: Ownership verification certificate expired

• AVAILABLE: Domain is ready and functional

# Check domain status
aws apigateway get-domain-name --domain-name api.mycompany.com --query 'domainNameStatus'

Certificate Conflict Resolution

If you get the error: "The certificate subject conflicts with an existing certificate from a different issuer":

1. Ensure all certificates for a subject come from the same issuer

2. Remove conflicting certificates from truststore

3. Contact AWS Support if you don't control the conflicting certificate

AWS CloudFormation Template for mTLS

For Infrastructure as Code deployment:

AWSTemplateFormatVersion: '2010-09-09'
Description: 'mTLS API Gateway Setup'

Parameters:
  DomainName:
    Type: String
    Default: api.mycompany.com
  TruststoreS3Uri:
    Type: String
    Default: s3://my-mtls-truststore-bucket/truststore/certificates.pem
  CertificateArn:
    Type: String
    Description: ACM Certificate ARN

Resources:
  CustomDomainName:
    Type: AWS::ApiGateway::DomainName
    Properties:
      DomainName: !Ref DomainName
      RegionalCertificateArn: !Ref CertificateArn
      EndpointConfiguration:
        Types:
          - REGIONAL
      SecurityPolicy: TLS_1_2
      MutualTlsAuthentication:
        TruststoreUri: !Ref TruststoreS3Uri

  BasePathMapping:
    Type: AWS::ApiGateway::BasePathMapping
    Properties:
      DomainName: !Ref CustomDomainName
      RestApiId: !Ref YourRestApi
      Stage: prod

Outputs:
  DistributionDomainName:
    Description: 'API Gateway distribution domain name for DNS'
    Value: !GetAtt CustomDomainName.DistributionDomainName

Step 6: Testing the mTLS Implementation

Generate Test Certificates

Create test certificates for development:

# Create a private CA
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -key ca-key.pem -out ca-cert.pem -days 365 \
    -subj "/C=US/ST=CA/L=San Francisco/O=MyCompany/CN=MyCompany CA"

# Create client certificate
openssl genrsa -out client-key.pem 4096
openssl req -new -key client-key.pem -out client-csr.pem \
    -subj "/C=US/ST=CA/L=San Francisco/O=acme-corp.com/CN=John Doe/[email protected]"

# Sign client certificate with CA
openssl x509 -req -in client-csr.pem -CA ca-cert.pem -CAkey ca-key.pem \
    -CAcreateserial -out client-cert.pem -days 365

# Add CA certificate to your truststore
cat ca-cert.pem >> certificates.pem

Test with curl

# Test the health endpoint
curl -v --key ./client-key.pem --cert ./client-cert.pem \
    https://api.mycompany.com/health

# Test user profile endpoint
curl -v --key ./client-key.pem --cert ./client-cert.pem \
    https://api.mycompany.com/profile

# Test secure data endpoint
curl -v --key ./client-key.pem --cert ./client-cert.pem \
    -H "Content-Type: application/json" \
    -d '{"data_type": "financial", "parameters": {"detailed": true}}' \
    https://api.mycompany.com/secure-data

# Expected failure scenarios
# 1. No certificate provided
curl -v https://api.mycompany.com/health
# Expected: SSL handshake failure

# 2. Invalid/expired certificate
curl -v --key ./expired-client-key.pem --cert ./expired-client-cert.pem \
    https://api.mycompany.com/health
# Expected: 403 Forbidden

# 3. Untrusted certificate issuer
curl -v --key ./untrusted-client-key.pem --cert ./untrusted-client-cert.pem \
    https://api.mycompany.com/health
# Expected: SSL handshake failure

Advanced Testing with OpenSSL

Test the TLS handshake directly:

# Test mTLS handshake
openssl s_client -connect api.mycompany.com:443 \
    -cert client-cert.pem -key client-key.pem \
    -verify_return_error -verify 1

# Check which server certificate is returned
openssl s_client -connect api.mycompany.com:443 -servername api.mycompany.com

# Test cipher suites
openssl s_client -connect api.mycompany.com:443 -cipher 'ECDHE-RSA-AES256-GCM-SHA384'

Python Test Client

import requests
import json

# Configure SSL context with client certificates
cert_file = 'client-cert.pem'
key_file = 'client-key.pem'
base_url = 'https://api.mycompany.com'

def test_mtls_api():
    """Test the mTLS-protected API endpoints"""
    
    # Test health endpoint
    response = requests.get(
        f'{base_url}/health',
        cert=(cert_file, key_file),
        verify=True  # Verify server certificate
    )
    print("Health Check:", response.json())
    
    # Test profile endpoint
    response = requests.get(
        f'{base_url}/profile',
        cert=(cert_file, key_file),
        verify=True
    )
    print("User Profile:", response.json())
    
    # Test secure data endpoint
    data = {
        "data_type": "financial",
        "parameters": {"detailed": True}
    }
    response = requests.post(
        f'{base_url}/secure-data',
        json=data,
        cert=(cert_file, key_file),
        verify=True
    )
    print("Secure Data:", response.json())

if __name__ == "__main__":
    test_mtls_api()

Security Best Practices

1. Certificate Management

• Use short-lived certificates: Implement certificate rotation policies

• Monitor certificate expiration: Set up alerts for expiring certificates

• Implement certificate revocation: Use OCSP or CRL for revoked certificates

• Secure private key storage: Use HSMs or secure key management services

2. Truststore Management

• Regular truststore updates: Keep your truststore current with valid CAs

• Version control: Use S3 versioning for truststore management

• Validation testing: Test certificate validation before updating truststores

• Backup strategies: Maintain secure backups of truststore configurations

3. API Security

• Disable default endpoints: Ensure clients can only access via custom domain

• Implement rate limiting: Add throttling to prevent abuse

• Add logging and monitoring: Track certificate usage and API access

• Use additional authentication: Combine mTLS with JWT or API keys for defense in depth

4. Monitoring and Alerting

• Certificate validation failures: Monitor and alert on authentication failures

• Unusual access patterns: Detect and investigate anomalous API usage

• Performance monitoring: Track API response times and availability

• Compliance auditing: Maintain logs for security and compliance requirements

Troubleshooting AWS API Gateway mTLS Issues

Certificate Validation Errors

Common Certificate Issues

1. Certificate Chain Problems

# Check certificate chain validity
openssl verify -CAfile ca-cert.pem -untrusted intermediate-cert.pem client-cert.pem

# Verify certificate hierarchy
openssl x509 -in client-cert.pem -noout -subject
openssl x509 -in client-cert.pem -noout -issuer

2. Algorithm Mismatch

# Check certificate signature algorithm
openssl x509 -in client-cert.pem -noout -text | grep "Signature Algorithm"

# Supported algorithms:
# - SHA-256 or stronger
# - RSA-2048 or stronger  
# - ECDSA-256 or ECDSA-384

3. Certificate Expiration

# Check certificate validity dates
openssl x509 -in client-cert.pem -noout -dates

# Check if certificate is currently valid
openssl x509 -in client-cert.pem -noout -checkend 86400  # Check if expires in 24 hours

AWS API Gateway Specific Errors

Error: "The certificate subject conflicts with an existing certificate"

• Multiple CAs have issued certificates for the same subject

• Solution: Use certificates from a single CA for each subject

• Contact AWS Support if you don't control the conflicting certificate

Error: "Truststore warnings" in domain response

# Check domain warnings
aws apigateway get-domain-name --domain-name api.mycompany.com \
    --query 'mutualTlsAuthentication.truststoreWarnings'

# Decode certificates to identify problematic ones
openssl x509 -in certificate.crt -text -noout | grep Subject

Error: "PENDING_CERTIFICATE_REIMPORT" status

• Certificate reimport failed validation

• Check that Subject Alternative Names (SANs) match the domain

• Verify ownership verification certificate covers the domain

API Gateway Configuration Issues

Domain Name Status Issues

# Check domain status
aws apigateway get-domain-name --domain-name api.mycompany.com \
    --query 'domainNameStatus'

# Possible statuses and solutions:
# AVAILABLE - Ready to use
# PENDING - Still being created
# PENDING_CERTIFICATE_REIMPORT - Certificate validation failed
# PENDING_OWNERSHIP_VERIFICATION - Ownership cert expired

Base Path Mapping Problems

# List all base path mappings
aws apigateway get-base-path-mappings --domain-name api.mycompany.com

# Delete incorrect mapping
aws apigateway delete-base-path-mapping \
    --domain-name api.mycompany.com \
    --base-path old-path

# Create correct mapping
aws apigateway create-base-path-mapping \
    --domain-name api.mycompany.com \
    --rest-api-id your-api-id \
    --stage prod

S3 Truststore Issues

Truststore Access Problems

# Check S3 bucket permissions
aws s3api get-bucket-policy --bucket my-mtls-truststore-bucket

# Required API Gateway permissions for truststore access:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "apigateway.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-mtls-truststore-bucket/truststore/*"
        }
    ]
}

Truststore Format Issues

# Validate truststore format
openssl x509 -in certificates.pem -text -noout

# Check for common format issues:
# - Missing BEGIN/END markers
# - Extra whitespace or characters
# - Wrong encoding (must be PEM)
# - Certificate order (leaf to root)

# Fix format issues
dos2unix certificates.pem  # Remove Windows line endings

DNS and Connectivity Issues

DNS Resolution Problems

# Check DNS resolution
nslookup api.mycompany.com
dig api.mycompany.com CNAME

# Test API Gateway endpoint directly
curl -v https://d123456789.execute-api.us-east-1.amazonaws.com/prod/health \
    --resolve api.mycompany.com:443:d123456789.execute-api.us-east-1.amazonaws.com

SSL/TLS Connection Issues

# Test SSL handshake
openssl s_client -connect api.mycompany.com:443 -servername api.mycompany.com

# Check TLS version support
openssl s_client -connect api.mycompany.com:443 -tls1_2

# Test with specific cipher
openssl s_client -connect api.mycompany.com:443 -cipher ECDHE-RSA-AES256-GCM-SHA384

Common Error Messages and Solutions

Error	Cause	Solution
403 Forbidden	Certificate not trusted or invalid	Check truststore contains the issuing CA
SSL handshake failed	Certificate chain broken or wrong algorithm	Verify complete certificate chain
Connection timeout	DNS or network issue	Check DNS CNAME record and security groups
Invalid certificate	Expired or malformed certificate	Regenerate certificate with correct validity
Domain not found	Base path mapping missing	Create base path mapping for API

Monitoring and Logging

Enable CloudWatch Logging

# Enable execution logging for API Gateway
aws apigateway update-stage \
    --rest-api-id your-api-id \
    --stage-name prod \
    --patch-operations op=replace,path=/*/logging/loglevel,value=INFO

# Enable access logging
aws apigateway update-stage \
    --rest-api-id your-api-id \
    --stage-name prod \
    --patch-operations op=replace,path=/accessLogSettings/destinationArn,value=arn:aws:logs:us-east-1:123456789012:log-group:api-gateway-logs

Key Metrics to Monitor

• TLS handshake failures: Certificate validation errors

• 4xx errors: Client certificate issues

• 5xx errors: Server configuration problems

• Latency spikes: Certificate validation performance

• Throughput by client organization

Performance Optimization

Certificate Caching

# Implement client-side certificate caching
import ssl
import requests
from requests.adapters import HTTPAdapter

class MutualTLSAdapter(HTTPAdapter):
    def __init__(self, cert_file, key_file, *args, **kwargs):
        self.cert_file = cert_file
        self.key_file = key_file
        super().__init__(*args, **kwargs)
    
    def init_poolmanager(self, *args, **kwargs):
        kwargs['cert_file'] = self.cert_file
        kwargs['key_file'] = self.key_file
        kwargs['ssl_context'] = ssl.create_default_context()
        return super().init_poolmanager(*args, **kwargs)

# Use persistent connections
session = requests.Session()
session.mount('https://', MutualTLSAdapter('client-cert.pem', 'client-key.pem'))

mTLS Authentication Flow: Complete Sequence Diagram

To better understand how mTLS works in AWS API Gateway, let's visualize the complete authentication flow from client request to API response:

Understanding the Flow Components

1. DNS Resolution

• Client resolves the custom domain to API Gateway endpoint

• Route 53 or external DNS provider returns the API Gateway regional endpoint

2. TLS Handshake with mTLS

# Python client initiating mTLS connection
import requests

response = requests.get(
    'https://api.mycompany.com/secure-data',
    cert=('client-cert.pem', 'client-key.pem'),  # Client certificate + private key
    verify=True  # Verify server certificate
)

3. Certificate Validation Process

• Server Certificate: API Gateway presents its certificate from ACM

• Client Certificate: Client presents certificate in TLS handshake

• Truststore Check: API Gateway validates client cert against S3 truststore

• Chain Verification: Complete certificate chain validated (up to 4 levels)

4. Request Processing with Certificate Context

# How certificate information reaches your Lambda function
def lambda_handler(event, context):
    # Certificate info available in request context
    client_cert = event.get("requestContext", {}).get("identity", {}).get("clientCert", {})
    
    certificate_details = {
        "subject": client_cert.get("subjectDN", ""),
        "issuer": client_cert.get("issuerDN", ""),
        "serial": client_cert.get("serialNumber", ""),
        "validity": client_cert.get("validity", {})
    }
    
    # Your application logic here
    return process_request_with_cert_info(certificate_details)

Critical Security Checkpoints

Performance Characteristics

Operation	Typical Latency	Caching
DNS Resolution	5-50ms	Client-side cached
TLS Handshake	100-300ms	Connection reused
Truststore Fetch	10-50ms	API Gateway cached
Certificate Validation	5-20ms	Validation cached
Lambda Cold Start	200-1000ms	Minimize with provisioned concurrency
Application Logic	Varies	Optimize based on access patterns

Real-World Sequence Example

Here's what happens when a Python client makes an authenticated request:

# Python client making authenticated request
import requests
import json

def make_secure_api_call():
    """Example of Python client calling mTLS-protected API"""
    
    try:
        # 1. TLS handshake with client certificate
        response = requests.post(
            'https://api.mycompany.com/secure-data',
            cert=('client-cert.pem', 'client-key.pem'),
            json={
                "data_type": "financial",
                "parameters": {"detailed": True}
            },
            headers={'Content-Type': 'application/json'},
            timeout=30
        )
        
        # 2. Process response (if certificate was validated)
        if response.status_code == 200:
            secure_data = response.json()
            print(f"✅ Secure data retrieved: {secure_data['data_type']}")
            print(f"Access level: {secure_data['access_level']}")
            return secure_data
        else:
            print(f"❌ Request failed: {response.status_code}")
            return None
            
    except requests.exceptions.SSLError as e:
        print(f"❌ SSL/Certificate error: {e}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"❌ Request error: {e}")
        return None

# Usage
result = make_secure_api_call()

This sequence diagram illustrates the complete security flow that protects your APIs while maintaining performance and reliability.

Common Error Messages

Performance Considerations

Optimization Strategies

1. Certificate Caching: Implement client-side certificate caching

2. Connection Pooling: Reuse TLS connections when possible

3. Async Operations: Use asynchronous processing for non-blocking operations

4. Load Balancing: Distribute traffic across multiple API Gateway endpoints

Monitoring Metrics

Track these key performance indicators:

• TLS handshake duration

• Certificate validation time

• API response latency

• Error rates by certificate issuer

• Throughput by client organization

Conclusion

Implementing mTLS-protected REST API endpoints in AWS API Gateway provides enterprise-grade security for your applications. This comprehensive approach ensures that only authenticated clients with valid certificates can access your sensitive APIs.

The combination of AWS API Gateway's managed mTLS capabilities with a well-architected Python application creates a robust, scalable, and secure API platform. By following the best practices outlined in this guide, you can build confidence in your API security while maintaining excellent performance and user experience.

Remember to regularly review and update your certificate management processes, monitor your API usage patterns, and stay current with AWS security best practices to maintain the highest level of protection for your applications.

Additional Resources

• AWS API Gateway mTLS Documentation

• AWS Certificate Manager User Guide

• Cloudflare Learning: What is mTLS?

• FastAPI Security Documentation

• Python requests SSL Documentation