almacdkoriginverify

README

npm i -D @alma-cdk/origin-verify

Enforce API Gateway REST API, AppSync GraphQL API, or Application Load Balancer traffic via CloudFront by generating a Secrets Manager secret value which is used as a CloudFront Origin Custom header and a WAFv2 WebACL header match rule.

Essentially this is an implementation of AWS Solution “Enhance Amazon CloudFront Origin Security with AWS WAF and AWS Secrets Manager” without the secret rotation.

🚧   Project Stability

This construct is still versioned with v0 major version and breaking changes might be introduced if necessary (without a major version bump), though we aim to keep the API as stable as possible (even within v0 development). We aim to publish v1.0.0 soon and after that breaking changes will be introduced via major version bumps.

Getting Started

import { OriginVerify } from '@alma-cdk/origin-verify';
import { Distribution } from 'aws-cdk-lib/aws-cloudfront';

const api: RestApi; // TODO: implement the RestApi
const apiDomain: string; // TODO: implement the domain

const verification = new OriginVerify(this, 'OriginVerify', {
  origin: api.deploymentStage,
});

new Distribution(this, 'CDN', {
  defaultBehavior: {
    origin: new HttpOrigin(apiDomain, {
      customHeaders: {
        [verification.headerName]: verification.headerValue,
      },
      protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
    })
  },
})

For more detailed example usage see /examples directory.

Custom Secret Value

Additionally, you may pass in custom secretValue if you don't want to use a generated secret (which you should use in most cases):

const myCustomValue = SecretValue.unsafePlainText('foobar');

const verification = new OriginVerify(this, 'OriginVerify', {
  origin: api.deploymentStage,
  secretValue: myCustomValue,
});

Notes

Use OriginProtocolPolicy.HTTPS_ONLY!

In your CloudFront distribution Origin configuration use OriginProtocolPolicy.HTTPS_ONLY to avoid exposing the verification.headerValue secret to the world.

Why secretValue.unsafeUnwrap()?

Internally this construct creates the headerValue by using AWS Secrets Manager but the secret value is exposed directly by using secretValue.unsafeUnwrap() method: This is:

• required, because we must be able to set it into the WAFv2 WebACL rule
• required, because you must be able to set it into the CloudFront Origin Custom Header
• okay, because it's meant to protect the API externally and it's not considered as a secret that should be kept – well – secret within your AWS account

Documentation

Overview

Enforce origin traffic via CloudFront.

Enforce origin traffic via CloudFront.

Enforce origin traffic via CloudFront.

Enforce origin traffic via CloudFront.

Index

• func NewOriginVerify_Override(o OriginVerify, scope constructs.Construct, id *string, ...)
• func OriginVerify_IsConstruct(x interface{}) *bool
• func OriginVerify_OriginVerifyHeader() *string
• type IVerification
• type OriginVerify
  • func NewOriginVerify(scope constructs.Construct, id *string, props *OriginVerifyProps) OriginVerify
• type OriginVerifyProps

Functions

func NewOriginVerify_Override

func NewOriginVerify_Override(o OriginVerify, scope constructs.Construct, id *string, props *OriginVerifyProps)

Associates an origin with WAFv2 WebACL to verify traffic contains specific header with a secret value.

Use `verifyHeader` value to assign custom headers into CloudFront config.

Example:

import { OriginVerify } from '@alma-cdk/origin-verify';
import { Distribution } from 'aws-cdk-lib/aws-cloudfront';

const api: RestApi; // TODO: implement the RestApi
const apiDomain: string; // TODO: implement the domain

const verification = new OriginVerify(this, 'OriginVerify', {
origin: api.deploymentStage,
});

new Distribution(this, 'CDN', {
defaultBehavior: {
origin: new HttpOrigin(apiDomain, {
customHeaders: {
[verification.headerName]: verification.headerValue,
},
protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
})
},
})

Experimental.

func OriginVerify_IsConstruct

func OriginVerify_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func OriginVerify_OriginVerifyHeader

func OriginVerify_OriginVerifyHeader() *string

Types

type IVerification

type IVerification interface {
	// CloudFront Origin Custom Header name used in the WAFv2 WebACL verification.
	// Experimental.
	HeaderName() *string
	// Secret Value used as the CloudFront Origin Custom Header value.
	//
	// Example:
	//   'xxxxEXAMPLESECRET'
	//
	// Experimental.
	HeaderValue() *string
}

Interface describing the "contract" of return values from the constructor. Experimental.

type OriginVerify

type OriginVerify interface {
	constructs.Construct
	IVerification
	// CloudFront Origin Custom Header name used in the WAFv2 WebACL verification.
	// Experimental.
	HeaderName() *string
	// Secret Value used as the CloudFront Origin Custom Header value.
	//
	// Example:
	//   'xxxxEXAMPLESECRET'
	//
	// Experimental.
	HeaderValue() *string
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Associates an origin with WAFv2 WebACL to verify traffic contains specific header with a secret value. Experimental.

func NewOriginVerify

func NewOriginVerify(scope constructs.Construct, id *string, props *OriginVerifyProps) OriginVerify

Associates an origin with WAFv2 WebACL to verify traffic contains specific header with a secret value.

Use `verifyHeader` value to assign custom headers into CloudFront config.

Example:

import { OriginVerify } from '@alma-cdk/origin-verify';
import { Distribution } from 'aws-cdk-lib/aws-cloudfront';

const api: RestApi; // TODO: implement the RestApi
const apiDomain: string; // TODO: implement the domain

const verification = new OriginVerify(this, 'OriginVerify', {
origin: api.deploymentStage,
});

new Distribution(this, 'CDN', {
defaultBehavior: {
origin: new HttpOrigin(apiDomain, {
customHeaders: {
[verification.headerName]: verification.headerValue,
},
protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
})
},
})

Experimental.

type OriginVerifyProps

type OriginVerifyProps struct {
	// Origin to protect.
	//
	// Accepted types:
	// - `IStage` (from `aws-cdk-lib/aws-apigateway`)
	// - `IApplicationLoadBalancer` (from `aws-cdk-lib/aws-elasticloadbalancingv2`).
	// Experimental.
	Origin interface{} `field:"required" json:"origin" yaml:"origin"`
	// Metric name for the WebACL.
	// Experimental.
	AclMetricName *string `field:"optional" json:"aclMetricName" yaml:"aclMetricName"`
	// By default `x-origin-verify` is used.
	//
	// To override it, provide a value for
	// this. Recommendation is to use something with a `x-` prefix.
	// Experimental.
	HeaderName *string `field:"optional" json:"headerName" yaml:"headerName"`
	// Metric name for the allowed requests.
	// Experimental.
	RuleMetricName *string `field:"optional" json:"ruleMetricName" yaml:"ruleMetricName"`
	// Any additional rules to add into the created WAFv2 WebACL.
	// Experimental.
	Rules *[]interface{} `field:"optional" json:"rules" yaml:"rules"`
	// The secret which is used to verify the CloudFront distribution.
	//
	// Optional: By default this construct will generate a `new Secret`.
	// Experimental.
	SecretValue awscdk.SecretValue `field:"optional" json:"secretValue" yaml:"secretValue"`
}

Properties for `OriginVerify` constructor. Experimental.