How do I enable IAM authentication for API Gateway APIs?
Last updated: 2019-12-19
I want to enable AWS Identity and Access Management (IAM) authentication for access to my Amazon API Gateway API. How do I set that up?
Enable IAM authentication for an API method in the API Gateway console. Then use IAM policies (along with 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.
Enable IAM authentication for your API
- In the API Gateway console, choose the name of your API.
- In the Resources pane, choose a method (such as GET or POST) for which you want to enable IAM authentication.
- In the Method Execution pane, choose Method Request.
- Under Settings, for Authorization, choose the pencil icon (Edit), choose AWS_IAM from the dropdown menu, and then choose the check mark icon (Update).
- (Optional) Repeat steps 2-4 for each additional API method for which you want to enable IAM authentication.
- Deploy your API for the changes to take effect.
- In the Stage Editor pane, note the Invoke URL to use later for testing.
For more information, see Set up a Method Using the API Gateway Console and Obtain an API's Invoke URL in the API Gateway Console.
Grant API authorization to a group of IAM users
- Determine the permissions that you want your API users to have. For example, you can grant permissions so that users can only call your API, or you can grant permissions that allow users to create and manage APIs in your AWS account. For more information and considerations, see Control Access to an API with IAM Permissions.
- Create an IAM policy document that has the required permissions. For examples and formatting guidance, see the following:
Control Access for Invoking an API
IAM Policy Examples for API Execution Permissions
IAM Policy Examples for Managing API Gateway APIs
Note: To complete the testing instructions at the end of this article, you must allow invoke permissions.
- 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: You can grant API access to individual IAM users, but we recommend that you grant access at the IAM group level.
(Optional) Configure an API Gateway resource policy
You can use API Gateway resource policies (resource-based permissions) along with IAM policies (identity-based permissions) to further manage access to your API Gateway API. For more information, see IAM Authentication and Resource Policy and Identity-Based Policies and Resource-Based Policies.
Note: If you deny access to your API with a resource policy and allow access with an IAM policy (or vice versa), then access is still denied. Be sure to design your permissions structure so that these security features work together as expected for your use case. For more information, see Policy Evaluation Outcome Tables.
Send a request to test the authentication settings
As a test, use the Postman app to send a request to your API resource via the method (such as GET or POST) for which you enabled IAM authentication.
Note: To manually authenticate requests that are sent to API Gateway using another tool or environment, you must use the Signature Version 4 signing process. For more information, see Signing Requests in the API Gateway REST API Reference.
- 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 who is in the IAM group that has access to your API.
- In the URL field (Enter request URL), paste the invoke URL that you noted earlier. If you enabled IAM authentication on a method for a particular API resource, then append the resource name to the end of the invoke URL. The full request URL with resource name looks like this:
A successfully authenticated request returns a 200 OK response code. An unauthorized request returns the message "Missing Authentication Token" and a 403 Forbidden response code.