bgc-mtls-integration-plugin v1.4.0

bgc-mtls-integration-plugin

This plugin was created to simplify and automatize the process of enabling an Apigateway API to use Mutual TLS Authentication.

Table of contents

• 1. About mTLS
• 2. Prerequisites
• 3 Installation
• 4 Configuration
• 5 Running
• 6 Usage

• 6.1 Enable MTLS
• 6.2 Disable MTLS
• 6.3 Generate Secrets
• 6.4 Generate Certificate

• 7 Running tests
• 8 Issue Reporting

About mTLS

Mutual TLS authentication requires two-way authentication between the client and the server. With mutual TLS, clients must present X.509 certificates to verify their identity to access your API. Mutual TLS is a common requirement for Internet of Things (IoT) and business-to-business applications.

You can use mutual TLS along with other authorization and authentication operations that API Gateway supports. API Gateway forwards the certificates that clients provide to Lambda authorizers and to backend integrations.

To know more about mTLS visit the site mutual TLS authentication for AWS API Gateway

Prerequisites

Make sure you have the following installed before starting:

• nodejs

• npm

• serverless

The IAM role that is running the plugin will need the following permissions:

  apigateway:getDomainName            /*domain names GET*/
  apigateway:updateDomainName         /*domain names PATCH*/
  apigateway:updateRestApi            /*rest api*/
  apigateway:getRestApi            /*rest api*/
  apigateway:createDeployment         /*rest api*/
  route53:ChangeResourceRecordSets    /*hostedzone/{HostedZoneId}*/
  s3:listObjectVersions               /*s3 bucket*/
  secretsmanager:getSecretValue       /*secrets manager secrets*/

Installation

Use the package manager npm to install the plugin.

npm install bgc-mtls-integration-plugin

Then make the following edits to your serverless.yml file:

Add the plugin.

plugins:
  - bgc-mtls-integration-plugin

Add the plugin configuration

custom:
  mtls:
    componentName: ${self:service}-${self:custom.stage}
    authorityName: My Authority Name
    truststoreUri: ${cf:bgc-certificates-authority-${self:custom.stage}.TruststoreUri}
    hostedZoneId: ${cf:bgc-infra-${self:custom.stage}.HostedZoneId}
    restApiId: ${cf:${self:service}-${self:custom.stage}.ApiGatewayRestApiId}
    domains:
      [
        {
          certificateArn: '${cf:bgc-infra-${self:custom.stage}.CertificateArn}',
          domainName: 'my-domain.${cf:bgc-infra-${self:custom.stage}.HostedZoneName}',
        }
      ]

Configuration

It can accept the following options:

Running

It runs using serverless comands

  sls <command_name> [--parameter] <value>

Usage

The serverless commands provided by the plugin:

• sls enable_mtls: Use it to enable mtls on domain name (API)
• sls disable_mtls: Use it to disable mtls on domain name (API)
• sls generate_secrets: We need some secrets to use in mtls authentication, use this command to create it on secrets manager
• sls generate_certificate: Use it to generate the component certificates and save it to the secrets manager

Enable MTLS

Use it to enable mtls on domain name (API)

--disableDefault use it to disable apigateway default endpoint

  sls enable_mtls [--disableDefault false]

The process to enable mtls on ApiGateway domain name require six steps:

• VerifyDomain: step necessary to verify if the endpoint have required configuration to enable mtls
• AddEndpointType: step responsible for creating if needed an regional endpoint type for the domain name
• UpdateDNSRecord: step responsible for changing the DNS record to point to the new regional endpoint so it can start to receive traffic
• RemoveEndpointType: step responsible for removing EGDE endpoint type if exists, because you can only enable mtls on regional endpoints
• UpdateRestApi: step responsible for changing the type of the rest api to REGIONAL
• EnableMTLSOnApi: step responsible for associating the domain name with a truststore and enabling the mtls authentication
• DisableDefaultEndpoint: step responsible for removing the default endpoint of the api, so the api can only be accessed by mtls calls

Disable MTLS

Use it to disable mtls on domain name (API)

--domain domain name associated with the api (required)

  sls disable_mtls --domain 'api.domain.name'

Generate Secrets

We need some secrets to use in mtls authentication, use this command to create it on secrets manager

  sls generate_secrets

Generate Certificate

Use it to generate the component certificates and save it to the secrets manager

  sls generate_certificate

Running tests

  npm run test

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section.