Description

Ensure that every Amazon API Gateway REST API stage has a client certificate configured. API Gateway presents this certificate when it calls the HTTP backend, so the backend can verify that requests really come from API Gateway.

Rationale

Without a client certificate, the backend cannot tell whether a request came through API Gateway or was sent to it directly. Attackers who find the backend address can then bypass the authentication, throttling and other controls configured in API Gateway. Configuring a client certificate, and setting the backend to accept only requests signed with it, ensures that all traffic passes through API Gateway.

Impact

  • Allows the backend to verify that requests come from API Gateway

  • Prevents direct calls to the backend from bypassing API Gateway controls

  • The backend must be configured to validate the certificate, and the certificate must be rotated before it expires (one year after it is generated)

Default Value

API Gateway stages have no client certificate configured by default.

Pre-Requisites

  • IAM permissions: apigateway:GET, apigateway:POST, apigateway:PATCH (API Gateway administration)

  • An HTTP or HTTP proxy backend that can be configured to validate client certificates

  • Access to the backend server configuration to install the API Gateway certificate

Test Plan

Console:

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Open the API Gateway console and select a REST API.

  3. Select Stages and select a stage.

  4. In Stage details, check the Client certificate value.

  5. Repeat for each stage of each REST API in each region in use.

  6. If no client certificate is set for a stage, follow the implementation steps.

CLI:

List the stages of an API and their client certificate:

aws apigateway get-stages --region <REGION> --rest-api-id <REST_API_ID> --query "item[].[stageName,clientCertificateId]" --output table

A stage fails if clientCertificateId is empty (shown as None).

Implementation Steps

Console:

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Open the API Gateway console and select Client certificates in the left menu.

  3. Choose Generate certificate, enter a description and choose Generate.

  4. Copy the PEM-encoded certificate and configure the backend to accept only requests signed with it.

  5. Select APIs, open the REST API and select Stages.

  6. Select the stage, and in Stage details choose Edit.

  7. In Client certificate, select the certificate generated in step 3, then choose Save changes.

  8. Repeat for each stage of each REST API in each region in use.

CLI:

Generate a client certificate:

aws apigateway generate-client-certificate --description "API Gateway backend certificate"

Get the PEM certificate to install on the backend:

aws apigateway get-client-certificate --client-certificate-id <CLIENT_CERT_ID> --query pemEncodedCertificate --output text

Set the client certificate on the stage:

aws apigateway update-stage --rest-api-id <REST_API_ID> --stage-name <STAGE_NAME> --patch-operations op=replace,path=/clientCertificateId,value=<CLIENT_CERT_ID>

Backout Plan

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Open the API Gateway console, select the REST API and select Stages.

  3. Select the stage, and in Stage details choose Edit.

  4. In Client certificate, clear the selected certificate, then choose Save changes.

  5. If the backend was set to require the certificate, remove that requirement so that requests are not rejected.

Note: rolling back allows direct calls to the backend to go undetected again. Use it only as a temporary measure.

Reference