AWS apigateway high security documentation change
Summary
Restructured documentation with expanded variable reference sections, added template examples, and explicit guidance for escaping JavaScript input to prevent parsing errors
Security assessment
Added explicit guidance about using $util.escapeJavaScript() to prevent 400 errors from unparsable characters. This addresses potential security concerns around improper input handling that could lead to injection vulnerabilities or request processing failures.
Diff
diff --git a/apigateway/latest/developerguide/api-gateway-mapping-template-reference.md b/Users/docs/2025-03-10_15-36-52/apigateway/latest/developerguide/api-gateway-mapping-template-reference.md index fa3ae083b..2f59c2fb3 100644 --- a/apigateway/latest/developerguide/api-gateway-mapping-template-reference.md +++ b/apigateway/latest/developerguide/api-gateway-mapping-template-reference.md @@ -5 +5 @@ -Context variables for data transformationsInput variablesStage variablesUtil variables +$context Variables for data models, authorizers, mapping templates, and CloudWatch access logging$context Variable template example$context Variables for access logging only$input Variables$input Variable template examples$stageVariables$util Variables @@ -7 +7 @@ Context variables for data transformationsInput variablesStage variablesUtil var -# Variables for data transformations for API Gateway +# API Gateway mapping template and access logging variable reference @@ -9 +9 @@ Context variables for data transformationsInput variablesStage variablesUtil var -When you create a parameter mapping, you can use context variables as your data source. When you create mapping template transformations, you can use context variables, input, and util variables in scripts you write in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). For example mapping templates that use these reference variables, see [Examples using variables for mapping template transformations for API Gateway](./api-gateway-mapping-variable-examples.html). +This section provides reference information for the variables and functions that Amazon API Gateway defines for use with data models, authorizers, mapping templates, and CloudWatch access logging. For detailed information about how to use these variables and functions, see [Mapping templates for REST APIs](./models-mappings.html). For more information about the Velocity Template Language (VTL), see the [VTL Reference](https://velocity.apache.org/engine/devel/vtl-reference.html). @@ -11 +11 @@ When you create a parameter mapping, you can use context variables as your data -For a list of reference variables for access logging, see [Variables for access logging for API Gateway](./api-gateway-variables-for-access-logging.html). +###### Topics @@ -13 +13 @@ For a list of reference variables for access logging, see [Variables for access -## Context variables for data transformations + * $context Variables for data models, authorizers, mapping templates, and CloudWatch access logging @@ -15 +15,24 @@ For a list of reference variables for access logging, see [Variables for access -You can use the following `$context` variables for data transformations. + * $context Variable template example + + * $context Variables for access logging only + + * $input Variables + + * $input Variable template examples + + * $stageVariables + + * $util Variables + + + + +###### Note + +For `$method` and `$integration` variables, see [Amazon API Gateway API request and response data mapping reference](./request-response-data-mappings.html). + +## `$context` Variables for data models, authorizers, mapping templates, and CloudWatch access logging + +The following `$context` variables can be used in data models, authorizers, mapping templates, and CloudWatch access logging. API Gateway might add additional context variables. + +For `$context` variables that can be used only in CloudWatch access logging, see $context Variables for access logging only. @@ -76,5 +99,5 @@ API Gateway APIs can accept HTTP/2 requests, but API Gateway sends requests to b -`$context.requestOverride.header.`header_name`` | The request header override. If this parameter is defined, it contains the headers to be used instead of the **HTTP Headers** that are defined in the **Integration Request** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](./apigateway-override-request-response-parameters.html). -`$context.requestOverride.path.`path_name`` | The request path override. If this parameter is defined, it contains the request path to be used instead of the **URL Path Parameters** that are defined in the **Integration Request** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](./apigateway-override-request-response-parameters.html). -`$context.requestOverride.querystring.`querystring_name`` | The request query string override. If this parameter is defined, it contains the request query strings to be used instead of the **URL Query String Parameters** that are defined in the **Integration Request** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](./apigateway-override-request-response-parameters.html). -`$context.responseOverride.header.`header_name`` | The response header override. If this parameter is defined, it contains the header to be returned instead of the **Response header** that is defined as the **Default mapping** in the **Integration Response** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](./apigateway-override-request-response-parameters.html). -`$context.responseOverride.status` | The response status code override. If this parameter is defined, it contains the status code to be returned instead of the **Method response status** that is defined as the **Default mapping** in the **Integration Response** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](./apigateway-override-request-response-parameters.html). +`$context.requestOverride.header.`header_name`` | The request header override. If this parameter is defined, it contains the headers to be used instead of the **HTTP Headers** that are defined in the **Integration Request** pane. For more information, see [Use a mapping template to override an API's request and response parameters and status codes](./apigateway-override-request-response-parameters.html). +`$context.requestOverride.path.`path_name`` | The request path override. If this parameter is defined, it contains the request path to be used instead of the **URL Path Parameters** that are defined in the **Integration Request** pane. For more information, see [Use a mapping template to override an API's request and response parameters and status codes](./apigateway-override-request-response-parameters.html). +`$context.requestOverride.querystring.`querystring_name`` | The request query string override. If this parameter is defined, it contains the request query strings to be used instead of the **URL Query String Parameters** that are defined in the **Integration Request** pane. For more information, see [Use a mapping template to override an API's request and response parameters and status codes](./apigateway-override-request-response-parameters.html). +`$context.responseOverride.header.`header_name`` | The response header override. If this parameter is defined, it contains the header to be returned instead of the **Response header** that is defined as the **Default mapping** in the **Integration Response** pane. For more information, see [Use a mapping template to override an API's request and response parameters and status codes](./apigateway-override-request-response-parameters.html). +`$context.responseOverride.status` | The response status code override. If this parameter is defined, it contains the status code to be returned instead of the **Method response status** that is defined as the **Default mapping** in the **Integration Response** pane. For more information, see [Use a mapping template to override an API's request and response parameters and status codes](./apigateway-override-request-response-parameters.html). @@ -89 +112,49 @@ API Gateway APIs can accept HTTP/2 requests, but API Gateway sends requests to b -## Input variables +## `$context` Variable template example + +You might want to use `$context` variables in a mapping template if your API method passes structured data to a backend that requires the data to be in a particular format. + +The following example shows a mapping template that maps incoming `$context` variables to backend variables with slightly different names in an integration request payload: + +###### Note + +One of the variables is an API key. This example assumes that the method requires an API key. + + + { + "stage" : "$context.stage", + "request_id" : "$context.requestId", + "api_id" : "$context.apiId", + "resource_path" : "$context.resourcePath", + "resource_id" : "$context.resourceId", + "http_method" : "$context.httpMethod", + "source_ip" : "$context.identity.sourceIp", + "user-agent" : "$context.identity.userAgent", + "account_id" : "$context.identity.accountId", + "api_key" : "$context.identity.apiKey", + "caller" : "$context.identity.caller", + "user" : "$context.identity.user", + "user_arn" : "$context.identity.userArn" + } + +The output of this mapping template should look like the following: + + + { + stage: 'prod', + request_id: 'abcdefg-000-000-0000-abcdefg', + api_id: 'abcd1234', + resource_path: '/', + resource_id: 'efg567', + http_method: 'GET', + source_ip: '192.0.2.1', + user-agent: 'curl/7.84.0', + account_id: '111122223333', + api_key: 'MyTestKey', + caller: 'ABCD-0000-12345', + user: 'ABCD-0000-12345', + user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar' + } + +## `$context` Variables for access logging only + +The following `$context` variables are available only for access logging. For more information, see [Set up CloudWatch logging for REST APIs in API Gateway](./set-up-logging.html). (For WebSocket APIs, see [Monitor WebSocket API execution with CloudWatch metrics](./apigateway-websocket-api-logging.html).) @@ -91 +162,34 @@ API Gateway APIs can accept HTTP/2 requests, but API Gateway sends requests to b -You can use the following `$input` variables to refer to the method request payload and method request parameters. The following functions are available: +Parameter | Description +---|--- +`$context.authorize.error` | The authorization error message. +`$context.authorize.latency` | The authorization latency in ms. +`$context.authorize.status` | The status code returned from an authorization attempt. +`$context.authorizer.error` | The error message returned from an authorizer. +`$context.authorizer.integrationLatency` | The authorizer integration latency in ms. +`$context.authorizer.integrationStatus` | The status code returned from a Lambda authorizer. +`$context.authorizer.latency` | The authorizer latency in ms. +`$context.authorizer.requestId` | The AWS endpoint's request ID. +`$context.authorizer.status` | The status code returned from an authorizer. +`$context.authenticate.error` | The error message returned from an authentication attempt. +`$context.authenticate.latency` | The authentication latency in ms. +`$context.authenticate.status` | The status code returned from an authentication attempt. +`$context.customDomain.basePathMatched` | The path for an API mapping that an incoming request matched. Applicable when a client uses a custom domain name to access an API. For example if a client sends a request to `https://api.example.com/v1/orders/1234`, and the request matches the API mapping with the path `v1/orders`, the value is `v1/orders`. To learn more, see [Map API stages to a custom domain name for REST APIs](./rest-api-mappings.html). +`$context.endpointType` | The endpoint type of the API. +`$context.integration.error` | The error message returned from an integration. +`$context.integration.integrationStatus` | For Lambda proxy integration, the status code returned from AWS Lambda, not from the backend Lambda function code. +`$context.integration.latency` | The integration latency in ms. Equivalent to `$context.integrationLatency`. +`$context.integration.requestId` | The AWS endpoint's request ID. Equivalent to `$context.awsEndpointRequestId`. +`$context.integration.status` | The status code returned from an integration. For Lambda proxy integrations, this is the status code that your Lambda function code returns. +`$context.integrationLatency` | The integration latency in ms. +`$context.integrationStatus` | For Lambda proxy integration, this parameter represents the status code returned from AWS Lambda, not from the backend Lambda function code. +`$context.responseLatency` | The response latency in ms. +`$context.responseLength` | The response payload length in bytes. +`$context.status` | The method response status. +`$context.waf.error` | The error message returned from AWS WAF. +`$context.waf.latency` | The AWS WAF latency in ms. +`$context.waf.status` | The status code returned from AWS WAF. +`$context.xrayTraceId` | The trace ID for the X-Ray trace. For more information, see [Set up AWS X-Ray with API Gateway REST APIs](./apigateway-enabling-xray.html). + +## `$input` Variables + +The `$input` variable represents the method request payload and parameters to be processed by a mapping template. It provides the following functions: @@ -122 +226 @@ Variable and function | Description -## Stage variables +## `$input` Variable template examples @@ -124 +228,192 @@ Variable and function | Description -You can use the following stage variables as placeholders for ARNs and URLs in method integrations. For more information, see [Use stage variables for a REST API in API Gateway](./stage-variables.html). +The following examples show how to use the `$input` variables in mapping templates. You can use a mock integration or a Lambda non-proxy integration that returns the input event back to API Gateway to try these examples. + +### Parameter mapping template example + +The following example passes all request parameters, including `path`, `querystring`, and `header`, through to the integration endpoint via a JSON payload: + + + #set($allParams = $input.params()) + { + "params" : { + #foreach($type in $allParams.keySet()) + #set($params = $allParams.get($type)) + "$type" : { + #foreach($paramName in $params.keySet()) + "$paramName" : "$util.escapeJavaScript($params.get($paramName))" + #if($foreach.hasNext),#end + #end + } + #if($foreach.hasNext),#end + #end + } + } + +For a request that includes the following input parameters: + + * A path parameter named `myparam` + + * Query string parameters `querystring1=value1,value2&querystring2=value3` + + * Headers `"header1" : "value1"`, `"header2" : "value2"`, `"header3" : "value3"`. + + + + +The output of this mapping template should look like the following: + + + { + "params" : { + "path" : { + "path" : "myparam" + } + , "querystring" : { + "querystring1" : "value1,value2" + , "querystring2" : "value3" + } + , "header" : { + "header3" : "value3" + , "header2" : "value2" + , "header1" : "value1" + } + }