How to choose the right API Gateway auth method

Yan Cui

I help clients go faster for less using serverless technologies.

This article is brought to you by

Hookdeck: The Serverless Event Gateway

Hookdeck is a reliable and scalable serverless event gateway for sending, receiving, authenticating, transforming, filtering, and routing events between services in your event-driven architecture.

Learn more

Update 21/06/2020: following lots of feedback and questions on Twitter, I have updated the post to include a few more options.

Quite a few clients have asked me “Hey Yan, what API Gateway auth method should I use for this REST API?” so I thought I’d share my answer with everyone here.

This is the high-level decision tree I go through when deciding if and what auth method I should use. It’s directly applicable for over 90% of the use cases I have come across.

What about performing authentication and authorization inside the Lambda function itself?

The short answer is don’t do it!

When API Gateway rejects an unauthorized request, we don’t pay for the request. If we perform authentication and authorization inside our Lambda functions then we have to pay for both the API Gateway request and the Lambda invocation. This opens us up to naive denial-of-wallet attacks where attackers can generate lots of invalid requests against our API.

How do I use Auth0 or Okta for authentication?

With third-party systems such as Auth0 or Okta, we can integrate them with Cognito User Pools as SAML identity providers [1] (IDPs). That way, we can still use Cognito authorizer with API Gateway and Cognito User Pools would verify the identity of the caller with the SAML IDP.

How do I support social log-ins such as Facebook or Google?

Similar to the above, we can also integrate Facebook, Google, Amazon or Apple with Cognito User Pools as social identity providers [2].

Where does Cognito Identity Pool fit in?

With Cognito Identity Pools [3], we can exchange federated identities from external identity providers with temporary IAM credentials.

Cognito Identity Pools is often used to provide access to client apps so they can access AWS services directly. For example, to allow IoT devices to publish and receive messages to & from AWS IoT Core [4].

The same approach can be applied with API Gateway. In this case, we need to use AWS_IAM authentication and control access with IAM policies.

How can I use group-based authentication with Cognito User Pools?

This is possible with API Gateway, but it takes a lot of work as you can see from the official guide [5]:

  1. add user groups
  2. assign an IAM role to each group to control which endpoints users in the group can access
  3. assign precedence to groups because a user can belong to multiple groups, and you need to resolve to one IAM role
  4. submit the ID token from Cognito when you send a request to API Gateway
  5. write a custom Lambda authorizer function (that’s right, you can’t use a Cognito authorizer!) to generate the correct policy based on the ID token

It’s complicated…

With AppSync, this is supported out-of-the-box and is one of the reasons why I prefer working with AppSync over API Gateway nowadays.


What about API Gateway resource policy?

API Gateway resource policies [6] offer another layer of control on top of the auth method on individual methods. We can whitelist/blacklist a range of IPs or AWS accounts, and we can also restrict access to the API to VPCs (see here [7] for more details).

When we have internal tools that are only accessible through the company’s VPN, then we can use IP Whitelisting to restrict access to the VPN’s public IP addresses. However, this shouldn’t be the default. As much as possible, we should integrate the internal tool with a user management system such as Auth0 or Cognito and use the appropriate auth method.

IP Blacklisting is often used in conjunction with other authentication methods to explicitly deny a list of known, suspicious IPs. While this can be useful, it doesn’t scale well as it makes us responsible for maintaining the list of known, suspicious IPs. Also, where we have multiple REST APIs, we’d have to keep the resource policies in sync to keep out the bad actors. A much better approach is to configure a Web ACL in AWS WAF [8] and apply it to all our APIs.

We can use resource policy to make private APIs – that is, APIs that are only accessible through our VPCs. Much has been said about zero-trust networking [9], that is, no one should be trusted by default, even when they are already inside our network. So even when we use resource policy to enforce access through VPC, we should still employ one of the aforementioned auth methods in our REST APIs. Network security should be applied in addition to, not instead of, the layer 7 protections provided by API Gateway.

Finally, what about whitelisting AWS accounts? This is necessary when making cross-account API requests using AWS_IAM auth. The REST API needs to allow-list the caller’s AWS account (or user/role) before the caller is able to use its IAM policy to provide access to our APIs. For more information about cross-account access management with IAM, have a read of these pages from the IAM documentation:


I hope you’ve found this post useful. If you want to learn more about running serverless in production and what it takes to build production-ready serverless applications then check out my upcoming workshop, Production-Ready Serverless [12]!

In the workshop, I will give you a quick introduction to AWS Lambda and the Serverless framework, and take you through topics such as:

  • testing strategies
  • how to secure your APIs
  • API Gateway best practices
  • CI/CD
  • configuration management
  • security best practices
  • event-driven architectures
  • how to build observability into serverless applications

and much more!


[1] Adding SAML identity providers to a user pool

[2] Adding social identity providers to a user pool

[3] Cognito Identity Pools

[4] AWS IoT Core

[5] Cognito: Adding groups to a user pool

[6] Controlling access to an API with API Gateway resource policies

[7] Use VPC endpoint policies for private APIs in API Gateway

[8] Web access control lists (web ACLs)

[9] What is zero-trust networking?

[10] IAM tutorial: Delegate access across AWS accounts using IAM roles

[11] Cross-account policy evaluation logic

[12] Production-Ready Serverless workshop

Whenever you’re ready, here are 4 ways I can help you:

  1. Production-Ready Serverless: Join 20+ AWS Heroes & Community Builders and 1000+ other students in levelling up your serverless game. This is your one-stop shop for quickly levelling up your serverless skills.
  2. Do you want to know how to test serverless architectures with a fast dev & test loop? Check out my latest course, Testing Serverless Architectures and learn the smart way to test serverless.
  3. I help clients launch product ideas, improve their development processes and upskill their teams. If you’d like to work together, then let’s get in touch.
  4. Join my community on Discord, ask questions, and join the discussion on all things AWS and Serverless.