Use VPC endpoint policies for private APIs in API Gateway

To improve the security of your private API, you can create a VPC endpoint policy. A VPC endpoint policy is an IAM resource policy that you attach to a VPC endpoint. For more information, see Controlling Access to Services with VPC Endpoints.

You might want to create a VPC endpoint policy to do the following tasks.

• Allow only certain organizations or resources to access your VPC endpoint and invoke your API.

• Use a single policy and avoid session-based or role-based policies to control traffic to your API.

• Tighten the security perimeter of your application while migrating from on premises to AWS.

VPC endpoint policy considerations

The following are considerations for your VPC endpoint policy.

• The identity of the invoker is evaluated based on the Authorization header value. Depending on your authorizationType, this may lead to an 403 IncompleteSignatureException or an 403 InvalidSignatureException error. The following table shows the Authorization header values for each authorizationType.

  authorizationType	Authorization header evaluated?	Allowed Authorization header values
  NONE with the default full access policy	No	Not passed
  NONE with a custom access policy	Yes	Must be a valid SigV4 value
  IAM	Yes	Must be a valid SigV4 value
  CUSTOM or COGNITO_USER_POOLS	No	Not passed

• If a policy restricts access to a specific IAM principal, such as arn:aws:iam::account-id:role/developer, you must set the authorizationType of your API's method to AWS_IAM or NONE. For more instructions on how to set the authorizationType for a method, see Methods for REST APIs in API Gateway.

• VPC endpoint policies can be used together with API Gateway resource policies. The API Gateway resource policy specifies which principals can access the API. The endpoint policy specifies who can access the VPC and which APIs can be called from the VPC endpoint. Your private API needs a resource policy but you don't need to create a custom VPC endpoint policy.

VPC endpoint policy examples

You can create policies for Amazon Virtual Private Cloud endpoints for Amazon API Gateway in which you can specify the following.

• The principal that can perform actions.

• The actions that can be performed.

• The resources that can have actions performed on them.

To attach the policy to the VPC endpoint, you'll need to use the VPC console. For more information, see Controlling Access to Services with VPC Endpoints.

Example 1: VPC endpoint policy granting access to two APIs

The following example policy grants access to only two specific APIs via the VPC endpoint that the policy is attached to.

{
    "Statement": [
        {
            "Principal": "*",
            "Action": [
                "execute-api:Invoke"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*",
                "arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*"
            ]
        }
    ]
}

Example 2: VPC endpoint policy granting access to GET methods

The following example policy grants users access to GET methods for a specific API via the VPC endpoint that the policy is attached to.

{
    "Statement": [
        {
            "Principal": "*",
            "Action": [
                "execute-api:Invoke"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*"
            ]
        }
    ]
}

Example 3: VPC endpoint policy granting a specific user access to a specific API

The following example policy grants a specific user access to a specific API via the VPC endpoint that the policy is attached to.

In this case, because the policy restricts access to specific IAM principals, you must set the authorizationType of the method to AWS_IAM or NONE.

{
    "Statement": [
        {
            "Principal": {
                "AWS": [
                    "arn:aws:iam::123412341234:user/MyUser"
                ]
            },
            "Action": [
                "execute-api:Invoke"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*"
            ]
        }
    ]
}