Amazon API Gateway
Developer Guide

How Amazon API Gateway Resource Policies Affect Authorization Workflow

When API Gateway evaluates the resource policy attached to your API, the result is affected by the authentication type that you have defined for the API, as illustrated in the flowcharts in the following sections.

API Gateway Resource Policy Only

In this workflow, an API Gateway resource policy is attached to the API, but no authentication type is defined for the API. Evaluation of the policy will involve seeking an explicit allow based on the inbound criteria of the caller. An implicit denial or any explicit denial will result in denying the caller.

Following is an example of such a resource policy.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:region:account-id:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] }

Lambda Authorizer and Resource Policy

In this workflow, a Lambda authorizer is configured for the API in addition to a resource policy. The resource policy will be evaluated in two phases. Prior to calling the Lambda authorizer, API Gateway will first evaluate the policy and check for any explicit denials. If found, the caller is denied access immediately. Otherwise, the Lambda authorizer is called, and it returns a policy document, which is evaluated in conjunction with the resource policy. The result is determined based on Table A below.

The following example resource policy allows calls only from the VPC endpoint whose VPC endpoint ID is vpce-1a2b3c4d. During the pre-auth evaluation, only the calls coming from the VPC endpoint indicated below will be allow to move forward and evaluate the Lambda authorizer. All remaining calls will be blocked.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:region:account-id:api-id/" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] }

IAM Authentication and Resource Policy

In this workflow, IAM authentication is configured for the API in addition to a resource policy. After authenticating the user with the IAM service, the policies attached to the IAM user in addition to the resource policy are evaluated together. The outcome will vary based on whether the caller is in the same account, or a separate AWS account, from the API owner. If the caller and API owner are from separate accounts, both the IAM user policies and the resource policy explicitly allow the caller to proceed. (See Table B below.) In contrast, if the caller and the API owner are in the same account, then either the user policies or the resource policy must explicitly allow the caller to proceed. (See Table A below.)

Following is an example of a cross-account resource policy. Assuming the IAM user policy contains an Allow, this resource policy will allow calls only from the VPC whose VPC ID is vpc-2f09a348. (See Table B below.)

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:region:account-id:api-id/" ], "Condition" : { "StringEquals": { "aws:SourceVpc": "vpc-2f09a348" } } } ] }

Amazon Cognito Authentication and Resource Policy

In this workflow, an Amazon Cognito user pool is configured for the API in addition to a resource policy. API Gateway first attempts to authenticate the caller via Amazon Cognito. This is typically performed via a JWT token provided by the caller. If authentication is successful, the resource policy is evaluated independently, and an explicit allow is required. A deny or neither allow or deny will result in a deny. Following is an example of a resource policy that might be used together with Amazon Cognito User Pools.

Following is an example of a resource policy that allows calls only from specified source IPs, assuming that the Amazon Cognito authentication token contains an Allow. (See Table A below.)

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:region:account-id:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] }

Policy Evaluation Outcome Tables

Table A lists the resulting behavior when access to an API Gateway API is controlled by an IAM policy (or a Lambda or Amazon Cognito User Pools authorizer) and an API Gateway resource policy, both of which are in the same AWS account.

Table A: Account A Calls API Owned by Account A

IAM User Policy (or Lambda or Amazon Cognito User Pools authorizer) API Gateway Resource Policy Resulting Behavior
Allow Allow Allow
Allow Neither Allow nor Deny Allow
Allow Deny Explicit Deny
Neither Allow nor Deny Allow Allow
Neither Allow nor Deny Neither Allow nor Deny Implicit Deny
Neither Allow nor Deny Deny Explicit Deny
Deny Allow Explicit Deny
Deny Neither Allow nor Deny Explicit Deny
Deny Deny Explicit Deny

Table B lists the resulting behavior when access to an API Gateway API is controlled by an IAM policy (or a Lambda or Amazon Cognito User Pools authorizer) and an API Gateway resource policy, which are in different AWS accounts. If either is silent (neither allow nor deny), cross-account access is denied. This is because cross-account access requires that both the resource policy and the IAM policy (or a Lambda or Amazon Cognito User Pools authorizer) explicitly grant access.

Table B: Account B Calls API Owned by Account A

IAM User Policy (or Lambda or Amazon Cognito User Pools authorizer) API Gateway Resource Policy Resulting Behavior
Allow Allow Allow
Allow Neither Allow nor Deny Implicit Deny
Allow Deny Explicit Deny
Neither Allow nor Deny Allow Implicit Deny
Neither Allow nor Deny Neither Allow nor Deny Implicit Deny
Neither Allow nor Deny Deny Explicit Deny
Deny Allow Explicit Deny
Deny Neither Allow nor Deny Explicit Deny
Deny Deny Explicit Deny