AWS whitepapers documentation change
Summary
Added documentation for custom domain names in private APIs, including cross-account sharing via AWS RAM, TLS security configuration, and multi-Region architecture updates
Security assessment
The changes add details about using custom domain names to configure security measures during TLS handshake and certificate lifecycle management with AWS Certificate Manager. While this enhances security documentation, there's no evidence of addressing a specific vulnerability or incident.
Diff
diff --git a/whitepapers/latest/best-practices-api-gateway-private-apis-integration/rest-api.md b/whitepapers/latest/best-practices-api-gateway-private-apis-integration/rest-api.md index 12a714887..1e7f50eca 100644 --- a//whitepapers/latest/best-practices-api-gateway-private-apis-integration/rest-api.md +++ b//whitepapers/latest/best-practices-api-gateway-private-apis-integration/rest-api.md @@ -15 +15 @@ While designing a REST API, a key consideration is security. Use [least privileg -To make APIs accessible only from Amazon VPCs, you can use REST APIs with the private endpoint type. The traffic to the APIs will not leave the AWS network. There are three options to invoke a private API through different domain name system (DNS) names: +To make APIs accessible only from Amazon VPCs, you can use REST APIs with the private endpoint type. The traffic to the APIs will not leave the AWS network. There are four options to invoke a private API through different domain name system (DNS) names: @@ -18,0 +19,2 @@ To make APIs accessible only from Amazon VPCs, you can use REST APIs with the pr + * Custom domain names + @@ -34,0 +37 @@ Private DNS names | Enabled | Easy to set up | DNS issue with regional and +Custom domain names | Enabled | Custom domain name for private APIs | Additional setup of a custom domain name in API Gateway @@ -43,0 +47,6 @@ However, if you use a custom DNS server, a conditional forwarder must be set on +#### Custom domain names + +You can create a custom domain name for your private APIs. Use a custom domain name to provide API callers with a simpler and more intuitive URL. With a private custom domain name, you can reduce complexity, configure security measures during the TLS handshake, and control the certificate lifeycle of your custom domain name using AWS Certificate Manager (ACM). + +You can share your custom domain name to another AWS account using AWS Resource Access Manager or API Gateway. AWS RAM helps you securely share your resources across AWS accounts and within your organization or organizational units (OUs). Because of this, you can consume a custom domain name from your own AWS account or from another AWS account. For more information, see [Custom domain names for private APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html). + @@ -60 +69 @@ Each alias is generated after associating a VPC endpoint to a private API. The a -Unlike regional and edge-optimized endpoint types, private APIs require the use of a resource policy. Deployments without a resource policy _will fail_. For private APIs, there are additional keys within the condition block you can use in the resource policy, such as `aws:sourceVpc` and `aws:SourceVpce`. The `aws:sourceVpc` policy allows traffic to originate from specific VPCs, and `aws:SourceVpce` allows traffic originating from interface VPC endpoints. +Unlike Regional and edge-optimized endpoint types, private APIs require the use of a resource policy. Deployments without a resource policy _will fail_. For private APIs, there are additional keys within the condition block you can use in the resource policy, such as `aws:sourceVpc` and `aws:SourceVpce`. The `aws:sourceVpc` policy allows traffic to originate from specific VPCs, and `aws:SourceVpce` allows traffic originating from interface VPC endpoints. @@ -104,0 +114,34 @@ _REST private API cross-account architecture_ +### Cross-account architecture with a custom domain name + + + +_REST private API cross-account architecture with a custom domain name_ + +The setup of this architecture is the following: + + * The API provider creates a custom domain name for a private API in the provider's account. This account and the consumer's account are both managed in AWS Organizations. + + * The provider account shares the private custom domain name using AWS RAM. + + * The provider updates both the resource policy attached to the private API and the private custom domain name to grant access to the consumer's VPC endpoint to invoke the endpoint. + + * A VPC-enabled Lambda function in the consumer's account invokes the private API using the custom domain name. + + + + +The numbers in the diagram correspond to the following: + + 1. A VPC-enabled Lambda function resolves a custom domain. + + 2. Route 53 private hosted zone has a record for the custom domain name. + + 3. The Lambda function uses the VPC endpoint for the custom domain name to make an API request. + + 4. The request reaches the API Gateway custom domain name. + + 5. The request is routed to the backend API Gateway endpoint. + + + + @@ -137 +180 @@ Customers want to build active-active or active-passive multi-Region API deploym -The core solution has private APIs configured with Regional custom domain names associated with a certificate from [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/). Each Region has a VPC Endpoint setup for the private API gateway to be accessed from VPC. At the time of this writing, custom domain names are not supported for private APIs directly, so the solution uses an NLB in front of the API Gateway using the same certificates configured with the custom domain name. A Route 53 private hosted zone in each VPC has alias records pointing to the NLB with the desired [routing policy](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html). The following routing polices can help in achieving the multi-Region architecture for API Gateway: +The core solution has private APIs configured with custom domain names for private APIs associated with a certificate from [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/). Each Region has a VPC Endpoint set up to allow access to the private API from the VPC. The following routing polices can help in achieving the multi-Region architecture for API Gateway: @@ -146,3 +189 @@ The core solution has private APIs configured with Regional custom domain names -To resolve the private API custom domain name, there is an [inbound resolver endpoint](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-forwarding-inbound-queries.html) setup for both Regions, which provides two or more private IPs in each VPC across multiple availability zones to ensure high availability. This enables the resolution of the custom domain name using the VPC resolver. - -The previous solution uses an NLB, however, you can use an ALB instead if required. When using an ALB, target groups need to be created with VPC endpoint IP addresses. The target group health check path should be set to `/ping` (API Gateway service health check) to return a HTTP 200 success code, otherwise the health check will fail with a 403 response. The Route 53 private hosted zone in each VPC has alias records configured to point to ALB hostname with the desired routing policy. The API Gateway, VPC endpoint and Route 53 inbound resolver setup remains as described for the NLB. +To resolve the custom domain name, there is an [inbound resolver endpoint](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-forwarding-inbound-queries.html) setup for both Regions, which provides two or more private IPs in each VPC across multiple availability zones to ensure high availability. This enables the resolution of the custom domain name using the VPC resolver. @@ -154 +195 @@ The solution assumes mechanisms are in place to synchronize state (if any) acros - + @@ -158 +199,3 @@ _Multi-Region API Gateway integrated with on-premise network via Route53 Resolve - 1. The application server in the corporate data center needs to resolve an API Gateway Private domain name. It sends the query to its pre-configured DNS server. +The numbers in the diagram correspond to the following: + + 1. The application server in the corporate data center needs to resolve an API Gateway custom domain name for private APIs. It sends the query to its pre-configured DNS server. @@ -164 +207 @@ _Multi-Region API Gateway integrated with on-premise network via Route53 Resolve - 4. The domain name is resolved to the Network Load Balancer (NLB) in one of the Regions based on the Route 53 routing policy. + 4. The domain name is resolved to the interface VPC endpoint (execute-api) in one of the Regions based on the Route 53 routing policy. @@ -166 +209 @@ _Multi-Region API Gateway integrated with on-premise network via Route53 Resolve - 5. The NLB target group sends the request to the interface VPC endpoint. + 5. The interface VPC endpoint points to the custom domain name. @@ -168 +211 @@ _Multi-Region API Gateway integrated with on-premise network via Route53 Resolve - 6. The interface VPC endpoint points to the API gateway. + 6. The custom domain name is mapped to a private REST API. @@ -170 +213 @@ _Multi-Region API Gateway integrated with on-premise network via Route53 Resolve - 7. The API gateway authenticates the request and sends it to the target service, such as Lambda. + 7. API Gateway authenticates the request and sends it to the target service, such as Lambda.