Menu
Amazon API Gateway
Developer Guide

Use Client-Side SSL Certificates for Authentication by the Backend

You can use API Gateway to generate an SSL certificate and use its public key in the backend to verify that HTTP requests to your backend system are from API Gateway. This allows your HTTP backend to control and accept only requests originating from Amazon API Gateway, even if the backend is publicly accessible.

Note

Some backend servers may not support SSL client authentication as API Gateway does and could return an SSL certificate error. For a list of incompatible backend servers, see Known Issues.

The SSL certificates that are generated by API Gateway are self-signed and only the public key of a certificate is visible in the API Gateway console or through the APIs.

Generate a Client Certificate Using the API Gateway Console

  1. In the main navigation pane, choose Client Certificates.

  2. From the Client Certificates pane, choose Generate Client Certificate.

  3. Optionally, for Edit, choose to add a descriptive title for the generated certificate and choose Save to save the description. API Gateway generates a new certificate and returns the new certificate GUID, along with the PEM-encoded public key.

    
                          Create client-side SSL Certificate in API Gateway

You are now ready to configure an API to use the certificate.

Configure an API to Use SSL Certificates

These instructions assume you already completed Generate a Client Certificate Using the API Gateway Console.

  1. In the API Gateway console, create or open an API for which you want to use the client certificate. Make sure the API has been deployed to a stage.

  2. Choose Stages under the selected API and then choose a stage.

  3. In the Stage Editor panel, select a certificate under the Client Certificate section.

  4. To save the settings, choose Save Changes.

    
                        Configure client-side SSL Certificate for an API in API Gateway

After a certificate is selected for the API and saved, API Gateway uses the certificate for all calls to HTTP integrations in your API.

Test Invoke to Verify the Client Certificate Configuration

  1. Choose an API method. In Client, choose Test.

  2. From Client Certificate, choose Test to invoke the method request.

    
                          Test API authentication using client-side SSL Certificate in API Gateway

API Gateway presents the chosen SSL certificate for the HTTP backend to authenticate the API.

Configure Backend HTTPS Server to Verify the Client Certificate

These instructions assume you already completed Generate a Client Certificate Using the API Gateway Console and downloaded a copy of the client certificate. You can download a client certificate by calling clientcertificate:by-id of the API Gateway REST API or get-client-certificate of AWS CLI.

Before configuring a backend HTTPS server to verify the client SSL certificate of API Gateway, you must have obtained the PEM-encoded private key and a server-side certificate that is provided by a trusted certificate authority.

If the server domain name is myserver.mydomain.com, the server certificate's CNAME value must be myserver.mydomain.com or *.mydomain.com.

Supported certificate authorities include Let's Encrypt or one of API Gateway-Supported Certificate Authorities for HTTP and HTTP Proxy Integrations.

As an example, suppose that the client certificate file is apig-cert.pem and the server private key and certificate files are server-key.pem and server-cert.pem, respectively, For a Node.js server in the backend, you can configure the server similar to the following:

var fs = require('fs'); var https = require('https'); var options = { key: fs.readFileSync('server-key.pem'), cert: fs.readFileSync('server-crt.pem'), ca: fs.readFileSync('apig-crt.pem'), requestCert: true, rejectUnauthorized: true }; https.createServer(options, function (req, res) { res.writeHead(200); res.end("hello world\n"); }).listen(443);

For a node-express app, you can use the client-certificate-auth modules to authenticate client requests with PEM-encoded certificates.

For other HTTPS server, see the documentation for the server.

Rotate an Expiring Client Certificate

The client certificate generated by API Gateway is valid for 365 days. You must rotate the certificate before a client certificate on an API stage expires to avoid any downtime for the API. You can check the expiration date of certificate by calling clientCertificate:by-id of the API Gateway REST API or the AWS CLI command of get-client-certificate and inspecting the returned expirationDate property.

To rotate a client certificate, follow the steps below:

  1. Generate a new client certificate, by calling clientcertificate:create of the API Gateway REST API or the AWS CLI command of create-client-certificate. For purposes of discussions, we assume the new client certificate ID is ndiqef.

  2. Update the backend server to include the new client certificate. Do not remove the existing client certificate yet.

    Some server may require a restart to finish the update. Consult the server documentation to see if you must restart the server during the update.

  3. Update the API stage to use the new client certificate by calling stage:update of the API Gateway REST API, with the new client certificate ID (ndigef):

    PATCH /restapis/{restapi-id}/stages/stage1 HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20170603T200400Z Authorization: AWS4-HMAC-SHA256 Credential=... { "patchOperations" : [ { "op" : "replace", "path" : "/clientCertificateId", "value" : "ndiqef" } ] }

    or by calling the CLI command of update-stage.

  4. Update the backend server to remove the old certificate.

  5. Delete the old certificate from API Gateway by calling the clientcerfiticate:delete of the API Gateway REST API, specifying the clientCertificateId (a1b2c3) of the old certificate:

    DELETE /clientcertificates/a1b2c3

    or by calling the CLI command of delete-client-certificate:

    aws apigateway delete-client-certificate --client-certificate-id a1b2c3