aws_apigateway: Allow StepFunctionsIntegration to include specific headers
- 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
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