How do I activate IAM authentication for API Gateway REST APIs?

4 minute read

I want to activate AWS Identity and Access Management (IAM) authentication for access to my Amazon API Gateway (API Gateway) REST API. How do I set that up?

Short description

Turn on IAM authentication for an API method in the API Gateway console. Then, use IAM policies and resource policies to designate permissions for your API's users.

For more information about the different security features available for API Gateway, see Controlling and managing access to a REST API in API Gateway.


Turn on IAM authentication for your REST API

1.    In the API Gateway console, choose the name of your API.

2.    In the Resources pane, choose a method (such as GET or POST) that you want to activate IAM authentication for.

3.    In the Method Execution pane, choose Method Request.

4.    Under Settings, for Authorization, choose the pencil icon (Edit). Then, choose AWS_IAM from the dropdown list, and then choose the check mark icon (Update).

5.    (Optional) Repeat steps 2-4 for each API method that you want to activate IAM authentication for.

6.    Deploy your API for the changes to take effect.

7.    In the Stage Editor pane, copy the Invoke URL. You'll use the Invoke URL later for testing.

For more information, see Set up a method using the API Gateway console. Also, Obtain an API's invoke URL in the API Gateway console.

Grant API authorization to a group of IAM users

1.    Determine the permissions that you want your API users to have. For more information, see Control access to an API with IAM permissions.

2.    Create an IAM policy that includes the required permissions. For examples and formatting guidance, see the following:
Control access for invoking an API
IAM policy examples for API execution permissions
Amazon API Gateway identity-based policy examples
Note: To complete the testing instructions at the end of this article, you must allow invoke permissions.

3.    Attach your IAM policy to an IAM group by doing one of the following:
Attach the policy to an existing IAM group.
Attach the policy when creating a new IAM group.

For more information, see Create and attach a policy to an IAM User.

Note: It's a best practice to grant access at the IAM group level.

(Optional) Configure an API Gateway resource policy

You can also use API Gateway resource policies (resource-based permissions) along with IAM policies (identity-based permissions) to manage access to your API. For more information, see IAM authentication and resource policy and Identity-based policies and resource-based policies.

Important: If you deny access to your API with one type of IAM policy and allow access with another type of policy, access is denied. For more information, see Policy evaluation outcome tables.

Send a request to test the authentication settings

Use the Postman app to send a request to your API resource using the method that you activated IAM authentication for.

Note: To manually authenticate requests that are sent to API Gateway using another tool or environment, use the Signature Version 4 signing process. For more information, see Signing requests.

1.    In Postman, on the Authorization tab, do the following:
For Type, choose AWS Signature.
For AccessKey and SecretKey, enter the IAM access key ID and secret access key for an IAM user. The IAM user must be in the IAM group that has access to your API.

2.    In the Enter request URL field, paste your API's invoke URL. If you activated IAM authentication on a method for a particular API resource, then append the resource name to the end of the invoke URL.

Note: The full request URL with resource name looks like the following:

An authenticated request returns a 200 OK response code. An unauthorized request returns the message Missing Authentication Token and a 403 Forbidden response code.

Related information

How API Gateway resource policies affect authorization workflow