Enterprise integrations with other organizations almost always have security requirements that restrict access to API endpoints and resources and often these can also vary per environment (qa, stage, production). There are numerous ways to manage this including mutual TLS, HMAC signatures and the lowly IP clearance. These are all important ways of limiting access with varying degrees of security and many times are used in conjuction with one another for added security. This article talks about the simplest and arguably the least secure way of protecting assets. IP clearance is still a valid way to restrict external access to your API but before you rely solely on this approach I recommend that you also understand it's limitations and always strive to make sure anything that might expose PII or other sensitive data is secured by a more robust security stance such as mutual TLS.

Related Reading

My previous article regarding integrating SQS and API Gateway can be used as a reference when following this tutorial in case you have questions about how to handle setting up an API Gateway using CloudFormation in more detail. This article uses the same techniques and terminology except that restricting access based on IP is a small set of the features that can be added to an AWS API Gateway REST API resource.

Template Parameters

Clearing your API using IP addresses has the inherent problem that the third party you are giving access to can and likely will change their IP address which would effectively block access when that happens. To help with that scenario I recommend you set the IP addresses that you want to clear using a simple list template parameter with all the IP addresses you are working with. Here's an example of how that will look.

NOTE: The IP addresses listed in the above gist as well as the full gist reference below are simply Google's DNS IP addresses so will only serve to block access to your API so make sure you put in the IP address(es) you want to allow access to your API in this template parameter.

API

In order to show you how to configure IP clearance restrictions in your API I have created a very simple CloudFormation template using API Gateway that proxies all the requests coming into to it to JSON Placeholder which is a mock REST API that is freely available for development purposes. In order to test the API and confirm that restrictions are in place for IP clearance, you will need access to two different networks that issue your computer different IP addresses. A couple of options for this could be your corporate or private VPN, using a mobile hotspot or using your home computer and your office computer.

Configuration of IP address access

The x-amazon-apigateway-policy extension allows you to specify resource policies for your API. In this tutorial I'm simply going to use wildcards to force the entire API to use these gateway policies as this is a common technique when doing an enterprise integration with a third party but you can also get as granular as you like with path based policies as well, e.g. if you only have one route that you want a third party to access.

The main focus here is use of the Allow and Deny Effect's that are embedded in the resource policy Statement in the x-amazon-apigateway-policy extension. In our case we want to allow access to the entire API but explicitly Deny access to everyone whose IP address is not in the cleared IP address list we configured as a template parameter. This serves to restrict access to entire API in our case if your IP address isn't added as part of the resource policy.

Stacks

CloudFormation templates can be uploaded into the AWS Console or deployed via the AWS CLI or AWS IDE toolkits such as the AWS Toolkit for IntelliJ IDEA or AWS Toolkit for Visual Studio Code. I'm going to use the console for instructions for this part of the tutorial as it doesn't have any required dependencies to install that the AWS CLI or IDE plugins would.

I've created a gist that contains the full CloudFormation template so download that file before moving forward.

To create this stack head over to the AWS Console for CloudFormation here. On the CloudFormation console home page, click on the Create Stack button or if you already have stacks running in your account, you should land on the Stacks list view and from there you can click Create Stack and select "With New Resources(standard)". This should take you to a screen that looks like this:

Ensure that in the Prepare Template section that _Template is ready_ is selected, and in the Template source ensure _Upload a template file_ is selected. Next click Choose File and select the downloaded CloudFormation from the gist linked to above. Once selected click the Next button and you will be presented with the Specify Stack Details page:

Specify a stack name in the blank field and click Next and you will be taken to the Configure stack options screen. Here you can leave everything as is and click Next to move to the Review <your stack name> page. On this page you can also leave everything as is and simply click Create Stack.

After clicking Create Stack, you will now be taken to an event viewer of the creation of your stack where you can watch the resources being created. Clicking the Refresh arrow button will show any newly added events but the screen should update on its own as well. It typically takes a few seconds to build this API Gateway since it's so simple although it does depend on how busy AWS services are and could take more or less time.

You may notice on the left side of the event log that it will say CREATE COMPLETE once it's done generating the resources in the template. If you don't see that show up in a reasonable amount of time (a minute or two) try hitting the refresh button or reloading the page. If there are any errors the stack, they will be shown in red in the event log and the stack will rollback the resources.
If you do run into errors you can always hit the DELETE button to rollback all the resources and start over.

End Notes

Restricting access by clearing IP address is a very basic way to control who can access your REST API's and as you can see is very easy to configure with a few simple lines of CloudFormation and API Gateway. That said, it's important to understand that IP addresses can be spoofed and that without other security measures, this shouldn't be considered fully secure. I would always recommend that you talk to your architecture or operations security team about security questions up front before deciding on and implementing any approach.