Skip to content

Commit 54d369f

Browse files
julianwoodjulianwood
authored
Merge pull request #2706 from tustha/tustha-feature-apigw-private-cdn-private-ca
New serverless pattern - apigw-private-cdn-private-ca
2 parents bc5efdf + 35e2588 commit 54d369f

File tree

7 files changed

+555
-0
lines changed

7 files changed

+555
-0
lines changed

‎apigw-private-cdn-private-ca-sam/README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Private Custom Domain for Amazon API Gateway API Using AWS Certificate Manager and Amazon Private Certificate Authority
2+
3+
This pattern enables secure access to a private REST API Gateway using a private custom domain name. The solution utilizes SSL certificates managed by AWS Certificate Manager (ACM) and signed by Amazon Private Certificate Authority (PCA), ensuring secure and authenticated communication within the private network.
4+
5+
Learn more about this pattern at [Serverless Land Patterns](https://serverlessland.com/patterns/apigw-private-cdn-private-ca-sam).
6+
7+
You can update the template to add AWS resources through the same deployment process that updates your application code.
8+
9+
Important: This application uses various AWS Services and there are costs associated with these services after the Free Tier Usage - please see the [AWS Pricing Page](https://aws.amazon.com/pricing/) for more details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
10+
11+
### Requirements
12+
13+
- [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
14+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
15+
- [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) installed and configured
16+
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed and configured
17+
- [A VPC with subnets and a security group](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html). The security group must have following conditions:
18+
1. Inbound rule allowing 443 traffic on the VPC CIDR range.
19+
2. Outbound rule allowing 443 traffic on VPC CIDR range.
20+
21+
### AWS Private CA Cost Considerations
22+
23+
Amazon PCA incurs costs based on your chosen operating mode:
24+
- General-purpose mode: Allows issuing certificates with any validity period
25+
- Short-lived certificate mode: Limited to certificates valid for up to 7 days
26+
27+
Please refer to the [AWS Private CA pricing page](https://aws.amazon.com/private-ca/pricing/).
28+
29+
**Alternative Cost-Effective Solution:**
30+
31+
If cost is a concern, consider creating Amazon API Gateway private custom domain name which can be configured with a SSL/TLS certificate from:
32+
- Your existing enterprise/internal Private CA
33+
- A third-party public Certificate Authority
34+
- Any other Certificate Authority you trust
35+
36+
The certificate can be imported and managed through [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html).
37+
38+
### How it works
39+
40+
Please refer to the architecture diagram below:
41+
42+
![End to End Architecture](images/architecture.png)
43+
44+
This implementation consists of three major components:
45+
46+
1. Private Certificate Authority and API Gateway Setup:
47+
1. Create an PCA
48+
2. Issue a root certificate through the PCA
49+
3. Create a certificate in ACM using PCA's root certificate
50+
4. Create a private REST API in API gateway
51+
5. Create API Gateway's private custom domain configured with ACM certificate created in step 3
52+
6. Configure a Lambda function as the API Gateway backend processor
53+
7. Deploy the private REST API through API Gateway
54+
8. Associate the custom domain with the API Gateway stage
55+
56+
2. VPC Endpoints configurations for private communication:
57+
1. "acm-pca" VPC Endpoint - Facilitates communication with PCA
58+
2. "execute-api" VPC Endpoint - Provides private access to the REST API
59+
60+
3. DNS Configuration:
61+
1. Establish a private hosted zone for the domain name
62+
2. Create a CNAME record within the hosted zone for custom domain name
63+
3. Point API Gateway's private custom domain name to the "execute-api" VPC Endpoint DNS name
64+
65+
### Deployment Instructions
66+
67+
**Note**: Please make sure to follow the below steps in order to make sure the deployment is successful.
68+
69+
1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
70+
``` bash
71+
git clone https://github.com/aws-samples/serverless-patterns
72+
```
73+
2. Change directory to the pattern directory:
74+
```bash
75+
cd serverless-patterns/apigw-private-cdn-private-ca-sam
76+
```
77+
3. Execute the following AWS CLI commands after replacing the placeholders (indicated by <>) with their corresponding values:
78+
```bash
79+
# First, build the SAM application
80+
sam build
81+
82+
# Then deploy with guided deployment (recommended for first time)
83+
sam deploy --guided --stack-name apigw-private-cdn-private-ca-sam
84+
85+
# Or deploy with specific parameters directly
86+
sam deploy \
87+
--stack-name apigw-private-cdn-private-ca-sam \
88+
--parameter-overrides \
89+
VpcIdParameter=<vpc-id> \
90+
VpcEndpointSubnetIdsParameter=<subnet-id-1>,<subnet-id-2> \
91+
ApiVPCESecurityGroup=<security-group-id> \
92+
--capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
93+
--region <your-region>
94+
```
95+
4. To implement your own custom domain configuration, modify the SAM template.yaml file by updating two constant parameter's values: `CustomDomain` and `DomainName`:
96+
```bash
97+
Mappings:
98+
Constants:
99+
CustomDomain:
100+
Value: "apigw.example.com"
101+
DomainName:
102+
Value: "example.com"
103+
```
104+
105+
## Testing
106+
107+
1. Sign in to the AWS Management Console.
108+
2. Navigate to the AWS Lambda console.
109+
3. From the Lambda functions list, select the function containing 'APITestingLambdaFunction' in its name.
110+
4. Click the 'Test' button in the function's detail page.
111+
5. Review the execution results in the output section, which will contain the response from the private API Gateway API.
112+
113+
## Cleanup
114+
115+
To remove all resources deployed to your AWS account through AWS SAM:
116+
117+
```bash
118+
sam delete --stack-name apigw-private-cdn-private-ca-sam
119+
```
120+
121+
---
122+
123+
Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
124+
125+
SPDX-License-Identifier: MIT-0

‎apigw-private-cdn-private-ca-sam/apigw-private-cdn-private-ca-sam.json‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
{
2+
"title": "Private Custom Domain for Amazon API Gateway Private REST API",
3+
"description": "Create Amazon API Gateway private REST API with private custom domain name configured with private SSL certificate.",
4+
"language": "Python",
5+
"level": "200",
6+
"framework": "AWS SAM",
7+
"introBox": {
8+
"headline": "How it works",
9+
"text": [
10+
"1. Private Certificate Authority and API Gateway Setup:",
11+
"1.1 Create an PCA",
12+
"1.2 Issue a root certificate through the PCA",
13+
"1.3 Create a certificate in ACM using PCA's root certificate",
14+
"1.4 Create a private REST API in API gateway",
15+
"1.5 Create API Gateway's private custom domain configured with ACM certificate created in step 3",
16+
"1.6 Configure a Lambda function as the API Gateway backend processor",
17+
"1.7 Deploy the private REST API through API Gateway",
18+
"1.8 Associate the custom domain with the API Gateway stage",
19+
"2. VPC Endpoints configurations for private communication:",
20+
"2.1 'acm-pca' VPC Endpoint - Facilitates communication with PCA",
21+
"2.2 'execute-api' VPC Endpoint - Provides private access to the REST API",
22+
"3. DNS Configuration:",
23+
"3.1 Establish a private hosted zone for the domain name",
24+
"3.2 Create a CNAME record within the hosted zone for custom domain name",
25+
"3.3 Point API Gateway's private custom domain name to the 'execute-api' VPC Endpoint DNS name"
26+
]
27+
},
28+
"gitHub": {
29+
"template": {
30+
"repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/apigw-private-cdn-private-ca-sam",
31+
"templateURL": "serverless-patterns/apigw-private-cdn-private-ca-sam",
32+
"projectFolder": "apigw-private-cdn-private-ca-sam",
33+
"templateFile": "template.yaml"
34+
}
35+
},
36+
"resources": {
37+
"bullets": [
38+
{
39+
"text": "Custom domain names for private APIs in API Gateway",
40+
"link": "https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html"
41+
},
42+
{
43+
"text": "Tutorial: Create and invoke a custom domain name for private APIs",
44+
"link": "https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains-tutorial.html"
45+
}
46+
]
47+
},
48+
"deploy": {
49+
"text": [
50+
"See the GitHub repo for detailed deployment instructions."
51+
]
52+
},
53+
"testing": {
54+
"text": [
55+
"See the GitHub repo for detailed testing instructions."
56+
]
57+
},
58+
"cleanup": {
59+
"text": [
60+
"Delete the stack: <code>sam delete --stack-name apigw-private-cdn-private-ca-sam</code>."
61+
]
62+
},
63+
"authors": [
64+
{
65+
"name": "Vijay Shekhar Rao",
66+
"image": "./images/vijay.jpg",
67+
"bio": "Vijay Shekhar Rao is a Partner Solutions Architect working with global system integrators. Before joining AWS, Vijay spent several years architecting, building, managing, and troubleshooting complex infrastructure for critical systems. When not working, he enjoys time with his family and tries to stay healthy.",
68+
"linkedin": "vsr4321"
69+
},
70+
{
71+
"name": "Tushar Thapar",
72+
"image": "./images/tusharthapar.jpg",
73+
"bio": "Tushar Thapar is a Cloud Engineer at Amazon Web Services based in Australia.",
74+
"linkedin": "tushar-thapar-b76247120"
75+
}
76+
],
77+
"patternArch": {
78+
"icon1": {
79+
"x": 20,
80+
"y": 50,
81+
"service": "vpc-endpoint",
82+
"label": "VPC endpoint"
83+
},
84+
"icon2": {
85+
"x": 80,
86+
"y": 50,
87+
"service": "apigw",
88+
"label": "API Gateway REST API"
89+
},
90+
"line1": {
91+
"from": "icon1",
92+
"to": "icon2",
93+
"label": "custom domain name"
94+
}
95+
}
96+
}

‎apigw-private-cdn-private-ca-sam/example-pattern.json‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
{
2+
"title": "Private Custom Domain for Amazon API Gateway Private REST API",
3+
"description": "Create Amazon API Gateway private REST API with private custom domain name configured with private SSL certificate.",
4+
"language": "Python",
5+
"level": "200",
6+
"framework": "AWS SAM",
7+
"introBox": {
8+
"headline": "How it works",
9+
"text": [
10+
"1. Private Certificate Authority and API Gateway Setup:",
11+
"1.1 Create an PCA",
12+
"1.2 Issue a root certificate through the PCA",
13+
"1.3 Create a certificate in ACM using PCA's root certificate",
14+
"1.4 Create a private REST API in API gateway",
15+
"1.5 Create API Gateway's private custom domain configured with ACM certificate created in step 3",
16+
"1.6 Configure a Lambda function as the API Gateway backend processor",
17+
"1.7 Deploy the private REST API through API Gateway",
18+
"1.8 Associate the custom domain with the API Gateway stage",
19+
"2. VPC Endpoints configurations for private communication:",
20+
"2.1 'acm-pca' VPC Endpoint - Facilitates communication with PCA",
21+
"2.2 'execute-api' VPC Endpoint - Provides private access to the REST API",
22+
"3. DNS Configuration:",
23+
"3.1 Establish a private hosted zone for the domain name",
24+
"3.2 Create a CNAME record within the hosted zone for custom domain name",
25+
"3.3 Point API Gateway's private custom domain name to the 'execute-api' VPC Endpoint DNS name"
26+
]
27+
},
28+
"gitHub": {
29+
"template": {
30+
"repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/apigw-private-cdn-private-ca-sam",
31+
"templateURL": "serverless-patterns/apigw-private-cdn-private-ca-sam",
32+
"projectFolder": "apigw-private-cdn-private-ca-sam",
33+
"templateFile": "template.yaml"
34+
}
35+
},
36+
"resources": {
37+
"bullets": [
38+
{
39+
"text": "Custom domain names for private APIs in API Gateway",
40+
"link": "https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html"
41+
},
42+
{
43+
"text": "Tutorial: Create and invoke a custom domain name for private APIs",
44+
"link": "https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains-tutorial.html"
45+
}
46+
]
47+
},
48+
"deploy": {
49+
"text": [
50+
"See the GitHub repo for detailed deployment instructions."
51+
]
52+
},
53+
"testing": {
54+
"text": [
55+
"See the GitHub repo for detailed testing instructions."
56+
]
57+
},
58+
"cleanup": {
59+
"text": [
60+
"Delete the stack: <code>sam delete --stack-name apigw-private-cdn-private-ca-sam</code>."
61+
]
62+
},
63+
"authors": [
64+
{
65+
"name": "Vijay Shekhar Rao",
66+
"image": "./images/vijay.jpg",
67+
"bio": "Vijay Shekhar Rao is a Partner Solutions Architect working with global system integrators. Before joining AWS, Vijay spent several years architecting, building, managing, and troubleshooting complex infrastructure for critical systems. When not working, he enjoys time with his family and tries to stay healthy.",
68+
"linkedin": "vsr4321"
69+
},
70+
{
71+
"name": "Tushar Thapar",
72+
"image": "./images/tusharthapar.jpg",
73+
"bio": "Tushar Thapar is a Cloud Engineer at Amazon Web Services based in Australia.",
74+
"linkedin": "tushar-thapar-b76247120"
75+
}
76+
]
77+
}

‎apigw-private-cdn-private-ca-sam/images/architecture.png‎

107 KB
Loading

‎apigw-private-cdn-private-ca-sam/images/tusharthapar.jpg‎

301 KB
Loading

‎apigw-private-cdn-private-ca-sam/images/vijay.jpg‎

8.65 KB
Loading

0 commit comments

Comments
 (0)