aws / aws/aws-cdk

(aws-apigateway): Add security policy and endpoint access mode support to RestApi L2 construct

Open
#36,663 3 comments 13 reactions 0 assignees View on GitHub
@aws-cdk/aws-apigateway effort/medium feature-request mixins p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the feature

Add native support for `securityPolicy` and `endpointAccessMode` properties to the `RestApi` L2 construct.

Currently, these security-critical properties are only available on the underlying `CfnRestApi` L1 construct, forcing developers to use escape hatches to configure enhanced security policies like `SecurityPolicy_TLS13_1_2_PQ_2025_09` and endpoint access modes (`BASIC` or `STRICT`).

This feature would expose these properties directly in `RestApiProps`, making security configuration more discoverable and eliminating the need for escape hatches when setting API Gateway security policies.

### Use Case

I'm always frustrated when I need to configure security policies for API Gateway REST APIs because the L2 construct doesn't expose these critical security properties. This forces me to use escape hatches, which breaks the abstraction layer and makes the code less maintainable. When working with compliance requirements or security-hardened environments, I need to set enhanced security policies like `SecurityPolicy_TLS13_1_2_PQ_2025_09` with endpoint access mode `STRICT`, but currently have to resort to accessing the underlying CloudFormation resource directly. This makes security configuration less discoverable for other developers and harder to enforce consistently across teams.

### Proposed Solution

Add `securityPolicy` and `endpointAccessMode` properties to `RestApiProps` interface and pass them through to the underlying `CfnRestApi` construct.

**Proposed API:**
``` python
api = apigateway.RestApi(
self, "MyApi",
rest_api_name="My API",
security_policy=apigateway.SecurityPolicy.TLS13_1_2_PQ_2025_09,
endpoint_access_mode=apigateway.EndpointAccessMode.BASIC
)
```

**Current workaround:**
``` python
api = apigateway.RestApi(self, "MyApi", rest_api_name="My API")
cfn_api = api.node.default_child
cfn_api.security_policy = "SecurityPolicy_TLS13_1_2_PQ_2025_09"
cfn_api.endpoint_access_mode = "BASIC"
```

### Other Information

**Alternative solutions considered:**
- Continue using escape hatches (current approach) - but this breaks abstraction and makes code less maintainable
- Create a custom L2 construct wrapper - adds unnecessary complexity and duplication
- Use `SpecRestApi` with OpenAPI definitions - more complex for simple use cases and doesn't solve the core issue

**Related context:**
- AWS API Gateway enhanced security policies were introduced to support modern TLS versions, FIPS compliance, and post-quantum cryptography
- Enhanced security policies require `endpointAccessMode` to be explicitly set (unlike legacy policies)
- Security policies are endpoint-type dependent (EDGE vs REGIONAL support different policies)
- AWS Documentation: [Security policies for REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-security-policies.html)

**Implementation considerations:**
- Should validate that enhanced security policies (starting with `SecurityPolicy_`) require `endpointAccessMode`
- Should validate security policy compatibility with endpoint type (EDGE has limited policy support)
- Consider adding helper methods or validation to guide users toward compatible combinations
- Existing `DomainName` construct already has `securityPolicy` support, so there's precedent for the enum structure

### Acknowledgements

- [ ] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

2.232.2

### AWS CDK CLI version

2.1100.3 (build 0aa3e98)

### Environment details (OS name and version, etc.)

Ubuntu 24.04.3 LTS

Contributor guide

Open the contributing guide

Research direction

Start with the RestApi L2 construct and its RestApiProps definition, then trace how properties are passed to the underlying CfnRestApi. Review the existing DomainName securityPolicy support for enum conventions. Done means both properties are exposed without escape hatches, reach the synthesized resource, and the expected enhanced-policy and endpoint-mode combinations are addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
api, cloud, security
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.