Skip to main content

API Gateway REST API Client Certificate Enabled

Overview​

This check verifies that your API Gateway REST API stages have a client certificate configured. Client certificates enable mutual TLS (mTLS) authentication between API Gateway and your backend services, ensuring that backend requests can be verified as originating from your API Gateway.

Risk​

Without client certificates enabled:

  • Backend bypass attacks become possible since your backend cannot verify requests are coming from API Gateway
  • Unauthorized direct access to backend services may occur, circumventing API Gateway policies and rate limits
  • Data integrity is compromised as malicious actors could inject or modify requests
  • Reduced audit capability since you cannot trace requests back to their API Gateway origin
  • Compliance violations for standards requiring mutual authentication between services

Remediation Steps​

Prerequisites​

  • AWS account access with permission to manage API Gateway resources
  • An existing REST API with at least one deployed stage
  • Your backend must be configured to trust API Gateway client certificates

AWS Console Method​

  1. Sign in to the AWS Management Console
  2. Navigate to API Gateway
  3. Select your REST API from the list
  4. In the left navigation pane, click Client Certificates
  5. Click Generate Client Certificate
  6. Optionally, add a description (e.g., "Certificate for backend authentication")
  7. Click Generate and note the certificate ID
  8. Now, in the left navigation pane, click Stages
  9. Select the stage you want to configure (e.g., prod, dev)
  10. In the Stage Editor, scroll down to Client Certificate
  11. From the dropdown, select the client certificate you generated
  12. Click Save Changes

Important: After enabling the client certificate, you must configure your backend server to trust this certificate. Export the certificate PEM from the console and add it to your backend's trusted CA store.

AWS CLI (optional)

Step 1: Generate a client certificate

aws apigateway generate-client-certificate \
    --description "Client certificate for backend mTLS" \
    --region us-east-1

Note the clientCertificateId from the output.

Step 2: Associate the certificate with your stage

aws apigateway update-stage \
    --rest-api-id <your-rest-api-id> \
    --stage-name <your-stage-name> \
    --patch-operations op=replace,path=/clientCertificateId,value=<client-certificate-id> \
    --region us-east-1

Replace:

  • <your-rest-api-id> with your API's ID (e.g., abc123def4)
  • <your-stage-name> with your stage name (e.g., prod)
  • <client-certificate-id> with the ID from step 1

To list existing client certificates:

aws apigateway get-client-certificates --region us-east-1

To get your REST API ID:

aws apigateway get-rest-apis --region us-east-1
CloudFormation (optional)

Deploy a client certificate and associate it with an API Gateway stage:

AWSTemplateFormatVersion: '2010-09-09'
Description: API Gateway REST API with client certificate enabled

Parameters:
  RestApiId:
    Type: String
    Description: The ID of your existing REST API
  StageName:
    Type: String
    Default: prod
    Description: The name of the stage to configure

Resources:
  ClientCertificate:
    Type: AWS::ApiGateway::ClientCertificate
    Properties:
      Description: Client certificate for backend mutual TLS authentication

  ApiStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      RestApiId: !Ref RestApiId
      StageName: !Ref StageName
      ClientCertificateId: !Ref ClientCertificate
      Description: Stage with client certificate enabled

Outputs:
  ClientCertificateId:
    Description: The ID of the generated client certificate
    Value: !Ref ClientCertificate
  ClientCertificatePem:
    Description: The PEM-encoded client certificate
    Value: !GetAtt ClientCertificate.PemEncodedCertificate

Deploy the template:

aws cloudformation deploy \
    --template-file apigateway-client-cert.yaml \
    --stack-name apigateway-client-cert-stack \
    --parameter-overrides RestApiId=<your-rest-api-id> StageName=prod \
    --region us-east-1

Note: If you have an existing stage, you may need to import it into CloudFormation or update it separately.

Terraform (optional)

Create a client certificate and associate it with an API Gateway stage:

resource "aws_api_gateway_client_certificate" "backend_cert" {
  description = "Client certificate for backend mutual TLS authentication"

  tags = {
    Purpose = "BackendAuthentication"
  }
}

resource "aws_api_gateway_stage" "example" {
  deployment_id         = aws_api_gateway_deployment.example.id
  rest_api_id           = aws_api_gateway_rest_api.example.id
  stage_name            = "prod"
  client_certificate_id = aws_api_gateway_client_certificate.backend_cert.id

  tags = {
    Environment = "Production"
  }
}

To update an existing stage with a client certificate:

# Reference existing REST API
data "aws_api_gateway_rest_api" "existing" {
  name = "my-existing-api"
}

# Create client certificate
resource "aws_api_gateway_client_certificate" "backend_cert" {
  description = "Client certificate for backend mutual TLS authentication"
}

# Import and manage existing stage with certificate
resource "aws_api_gateway_stage" "existing" {
  rest_api_id           = data.aws_api_gateway_rest_api.existing.id
  stage_name            = "prod"
  deployment_id         = "<current-deployment-id>"
  client_certificate_id = aws_api_gateway_client_certificate.backend_cert.id
}

Output the certificate PEM for backend configuration:

output "client_certificate_pem" {
  description = "PEM-encoded certificate to configure on backend servers"
  value       = aws_api_gateway_client_certificate.backend_cert.pem_encoded_certificate
  sensitive   = true
}

Verification​

After enabling the client certificate, verify the configuration:

  1. Go to API Gateway in the AWS Console
  2. Select your REST API
  3. Click Stages in the left navigation
  4. Select your stage and confirm Client Certificate shows your certificate ID
  5. Test an API call to verify your backend accepts the certificate
CLI verification commands

Check if a stage has a client certificate configured:

aws apigateway get-stage \
    --rest-api-id <your-rest-api-id> \
    --stage-name <your-stage-name> \
    --region us-east-1

Look for the clientCertificateId field in the output:

{
    "stageName": "prod",
    "clientCertificateId": "abc123",
    "cacheClusterEnabled": false,
    ...
}

If clientCertificateId is present and not null, the certificate is configured.

List all client certificates in your account:

aws apigateway get-client-certificates --region us-east-1

Additional Resources​

Notes​

  • Backend configuration required: After generating the certificate, you must export the PEM and configure your backend to trust it. The certificate alone does not provide security without backend verification.
  • Certificate expiration: Client certificates expire after approximately one year. Monitor expiration dates and rotate before they expire to avoid service disruptions.
  • Regional scope: Client certificates are regional. If you have APIs in multiple regions, create certificates in each region.
  • HTTP/HTTPS integrations only: Client certificates apply to HTTP and HTTPS backend integrations. They do not apply to Lambda, AWS service, or mock integrations.
  • Cost: There is no additional charge for API Gateway client certificates.
  • Certificate rotation: When rotating certificates, update your backend to trust the new certificate before removing the old one from API Gateway to avoid downtime.