Hero #18
Posted on 31 October, 2017 by Siddharth Dubey

Securing APIs on AWS API Gateway

APIs are fast becoming the go-to integration pattern for many organisations and developers, because they are a great integration practice that take the core SOA principles to the next level. The advantage of AWS API Gateway is that it supports multiple ‘AWS provided’ mechanisms to control API access in the AWS eco-system such as: API keys, AWS IAM roles and Amazon Cognito user pools.

One of the key concerns for every enterprise developer is securing APIs when they are exposed on an API Gateway. In this blog I will share with you the pros and cons of each API Gateway option provided by AWS and their use-cases.

Option 1: Securing the AWS API Gateway Using API-Keys

API-Keys together with AWS Usage-Plan can be set-up for each API on an AWS API Gateway. They can be used to provide access control, including metering or tracking of APIs. API-Keys can also be auto generated on AWS console. Each API method can be enabled to only allow access if the HTTP request header contains the correct API-Keys.

The steps to enable security using API-Keys are:

  1. Enable API-Keys on AWS console for API methods, and the need for security.

  2. Generate API-Keys (either using console or AWS APIs) and associate them with APIs together with Usage-Plan.

  3. Share the generated API-Key (either manually or via AWS Developer portal) with the API consumers.

  4. API consumers then sends the API-Key as a HTTP header in the API request.

  5. AWS API Gateway checks the header and compares it with the key associated with the API.

API-Keys are simple and easy to use. AWS supports API consumer registration via the AWS developer portal. Consumers can register and manage API-Keys via this portal. API-Keys are best suited for intra application integrations. For example internal System to System API calls) or from an external system where it is not possible to run AWS SDK. API-Keys should be avoided for any external system to API integration.

Option 2: Securing the AWS API Gateway with AWS IAM roles

Access to APIs deployed on AWS API Gateway can also be controlled using IAM permissions. The API consumer must have the necessary IAM permissions to be able to access the API. The steps to enable security using IAM roles are:

  1. The API consumer registers as an IAM User.

  2. The API developer then attaches the policy:

    a. to an IAM user representing the API consumer,

    b. or to an IAM group containing the user,

    c. or to an IAM role assumed by the user.

  3. The API developer sets the API method's authorizationType property to AWS_IAM to ensure the API security.

  4. The API consumer then invokes the API using its user-credentials.

  5. The AWS API Gateway upon receiving the HTTP request verifies the policies attached with the IAM user and authenticates the consumer before passing the request to the backend system.

The advantage of using IAM roles is that it can be used to configure multiple policies for other AWS components. Therefore, an AWS API exposing AWS Lambda/Beanstalk can potentially use a consumer’s IAM policies to access control each of the backend components. However, it should be noted that not all systems support the AWS SDK, and to use IAM roles an external API consumer needs to run the SDK to generate sigV4 AWS user-credentials.

Option 3: Securing the AWS API Gateway using Amazon Cognito

Amazon Cognito User-Pool can also be used to control API access on AWS API Gateway. A User-Pool serves as an identity provider and maintains a user directory. It supports user registration/ sign-in, and provisions identity (JWT) tokens for signed-in users.

The steps to enable security using Cognito are:

  1. The API developer creates a User-Pool, and creates an API Gateway authoriser connected to the User-Pool and enables the authoriser on selected API methods.

  2. The API developers shares the User-Pool ID, a client ID, and possibly the associated client secret with the API consumer.

  3. The API consumer then registers with the User-Pool. The User-Pool provides the sign-in functionality, and provisions the identity (JWT) token to the signed in consumer.

  4. The API consumer then sends the JWT token with the HTTP request.

  5. The API Gateway verifies the JWT token to ensure it belongs to the configured User-Pool and authenticates the consumer before passing the request to the backend system.

Amazon Cognito is suited for external systems to API calls, preferably from a mobile or web based application. A custom authoriser can be configured in AWS API Gateway to verify JWT tokens and attach appropriate policies with the HTTP requests. Cognito comes with many additional features such as Multi Factor Authentication (MFA), Identity federation with external identity providers like Google and Facebook, Open ID and SAML authentication.


With the increasing demand for API development, these methods will enable you to control API access to an AWS API Gateway. However, it is important that you select the correct option based on the appropriate use-case. API-Keys are best used for any intra-application API calls, while AWS Cognito is a best fit for any external system API calls. It is also important to consider that not all API Consumer systems support SigV4 (the AWS SDK). With this consideration, IAM roles could also be used to secure APIs.

Back to blog
Siddharth Dubey
Solution Designer

Siddharth is a Solution Designer with over 12 years of Java, SOA integration and performance engineering experience. Siddharth specialises in designing enterprise applications, and integrating them leveraging APIs, microservices and middleware technologies.