aws / aws/aws-cdk

aws_apigateway: Allow StepFunctionsIntegration to include specific headers

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

Description

### Describe the feature

Allow [StepFunctionExecutionIntegrationOptions#headers](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.StepFunctionsExecutionIntegrationOptions.html#headers) to accept a list of header names in addition to a boolean (or if limited by JSII, introduce a new property `headerNames`).

The generated request-mapping template should forward only the specified headers.
While `headers: true `could retain its current behaviour of forwarding all headers.

### Use Case

We need to forward a single non-sensitive header, `user-id`, to the Step Functions execution input. Using `headers: true` forwards all request headers, including sensitive values such as `Authorization` and `Cookie`, which may then appear in Step Functions execution history and logs, which I would like to avoid.

The alternative is to copy the existing template and adapt or write my own template. Dealing with vtl template is something we usually try to avoid.

Selective header forwarding would support least-privilege data handling, avoid accidental exposure of sensitive headers, and remove the need to maintain a custom Velocity mapping template.

### Proposed Solution

Keep the existing `headers?: boolean` property for backward compatibility and add a separate JSII-compatible property for selective forwarding in https://github.com/aws/aws-cdk/blob/v2.263.0/packages/aws-cdk-lib/aws-apigateway/lib/integrations/stepfunctions.ts#L18:

```typescript
export interface StepFunctionsExecutionIntegrationOptions extends IntegrationOptions {
/**
* Includes all request headers in the Step Functions execution input.
*/
readonly headers?: boolean;

/**
* Includes only the named request headers in the execution input.
* Mutually exclusive with `headers: true`.
*/
readonly headerNames?: string[];
}
```

### Other Information

The feature request could also work with a similar pattern with `querystring` (and maybe `path` but I don't have any use cases for allowing only specific paths)

### Acknowledgements

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

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

2.261.0

### AWS CDK CLI version

npx cdk --version

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

macos 26.6.1

Contributor guide

Open the contributing guide

Research direction

Start in packages/aws-cdk-lib/aws-apigateway/lib/integrations/stepfunctions.ts, especially StepFunctionsExecutionIntegrationOptions and the request-mapping template generation. Trace how headers: true is handled, then add selective forwarding for headerNames while preserving existing behavior; done means only the named headers reach the Step Functions execution input and the options remain mutually exclusive as described.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.