AWS serverless-application-model high security documentation change

Service: serverless-application-model · 2025-05-22 · Security-related high

File: serverless-application-model/latest/developerguide/sam-resource-api.md

Summary

Added documentation for the 'Policy' property in API Gateway resources and a new example of configuring a private API with custom domain and VPC endpoint restrictions

Security assessment

The change introduces explicit documentation for API resource policies that enforce access control via VPC endpoint conditions (aws:SourceVpce). This directly addresses security by restricting API access to authorized VPC endpoints, preventing unauthorized external access. The example includes explicit Deny policies with security conditions.

Diff

diff --git a/serverless-application-model/latest/developerguide/sam-resource-api.md b/serverless-application-model/latest/developerguide/sam-resource-api.md
index cf742cb54..8281a7dec 100644
--- a//serverless-application-model/latest/developerguide/sam-resource-api.md
+++ b//serverless-application-model/latest/developerguide/sam-resource-api.md
@@ -58,0 +59 @@ To declare this entity in your AWS Serverless Application Model (AWS SAM) templa
+      Policy: JSON
@@ -367,0 +369,11 @@ _AWS CloudFormation compatibility_ : This property is unique to AWS SAM and does
+`Policy`
+    
+
+A policy document that contains the permissions for the API. To set the ARN for the policy, use the `!Join` intrinsic function with `""` as delimiter and values of `"execute-api:/"` and `"*"`.
+
+_Type_ : JSON
+
+_Required_ : No
+
+_AWS CloudFormation compatibility_ : This property is passed directly to the [ Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) property of an `AWS::ApiGateway::RestApi` resource.
+
@@ -592,0 +605,93 @@ A Hello World AWS SAM template file that contains a Lambda Function with an API
+### Custom domain with a private API example
+
+A Hello World AWS SAM template file that contains a Lambda function with an API endpoint mapped to a private domain. The template creates a domain access association between a VPC endpoint and the private domain. 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).
+
+#### YAML
+    
+    
+    AWSTemplateFormatVersion: '2010-09-09'
+    Transform: AWS::Serverless-2016-10-31
+    Description: AWS SAM template configured with a custom domain using a private API
+    
+    Parameters:
+        DomainName:
+          Type: String
+          Default: mydomain.example.com
+        CertificateArn:
+          Type: String
+        HostedZoneId:
+          Type: String
+        VpcEndpointId:
+          Type: String
+        VpcEndpointDomainName:
+          Type: String
+        VpcEndpointHostedZoneId:
+          Type: String
+    
+    Resources:
+      MyFunction:
+        Type: AWS::Serverless::Function
+        Properties:
+          InlineCode: |
+            def handler(event, context):
+                return {'body': 'Hello World!', 'statusCode': 200}
+          Handler: index.handler
+          Runtime: python3.13
+          Events:
+            Fetch:
+              Type: Api
+              Properties:
+                RestApiId:
+                  Ref: MyApi
+                Method: Get
+                Path: /get
+      MyApi:
+        Type: AWS::Serverless::Api
+        Properties:
+          StageName: Prod
+          EndpointConfiguration:
+            Type: PRIVATE
+            VPCEndpointIds:
+            - !Ref VpcEndpointId
+          Policy:
+            Version: '2012-10-17'
+            Statement:
+            - Effect: Allow
+              Principal: '*'
+              Action: execute-api:Invoke
+              Resource: execute-api:/*
+            - Effect: Deny
+              Principal: '*'
+              Action: execute-api:Invoke
+              Resource: execute-api:/*
+              Condition:
+                StringNotEquals:
+                  aws:SourceVpce: !Ref VpcEndpointId
+          Domain:
+            DomainName: !Ref DomainName
+            CertificateArn: !Ref CertificateArn
+            EndpointConfiguration: PRIVATE
+            BasePath:
+            - /
+            Route53:
+              HostedZoneId: !Ref HostedZoneId
+              VpcEndpointDomainName: !Ref VpcEndpointDomainName
+              VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
+            AccessAssociation:
+              VpcEndpointId: !Ref VpcEndpointId
+            Policy:
+              Version: '2012-10-17'
+              Statement:
+              - Effect: Allow
+                Principal: '*'
+                Action: execute-api:Invoke
+                Resource: execute-api:/*
+              - Effect: Deny
+                Principal: '*'
+                Action: execute-api:Invoke
+                Resource: execute-api:/*
+                Condition:
+                  StringNotEquals:
+                    aws:SourceVpce: !Ref VpcEndpointId
+    
+