Introduction
AWS API Gateway supports Lambda function invocations over HTTPS. The Lambda functions can be used as a functional backend or as request custom authorizers.
When a senior AWS engineer creates a simple microservice using AWS API Gateway and Lambda functions, they need to grant permissions to the API Gateway that will allow invocation of those functions.
The permissions assignment mechanism is not always very obvious and this article depicts several ways how to achieve that.
AWS API Gateway and Lambda Functions
AWS API Gateway supports several types of backed integration: HTTP endpoint, Lambda function, Mock, etc. The Lambda function integration type is the most dominant approach because it allows building APIs that act as proxies that orchestrate and aggregate existing services and expose that way new, simplified functionality and user experience.
AWS API Gateway custom authorizers were introduced a couple of months ago. They shall be implemented as Lambda functions that evaluate authentication/authorization information in the HTTP request and return a policy authorization document.
The following sequence diagram represents a typical request processing flow for an API that relies on Lambda functions for request authentication/authorization as well as for functional backend logic.
The API Gateway allows custom authorization access control to the APIs using HTTP bearer token authentication. The authentication/authorization logic is encapsulated inside the Lambda function, known as Custom Authorizer. This Lambda function authorizes the client requests for the configured APIs. For failed authentication, the function throws an authentication error. For authenticated users, the function returns a policy document that enumerates the resources the user is authorized to use.
There are two types of permission policies involved when configuring Lambda function as a custom authorizer or backend in the AWS API Gateway:
- Permissions for your Lambda function– No matter who invokes a particular Lambda function, AWS Lambda executes the function by assuming an IAM role (execution role) specified at the time you created or updated that Lambda function. The permission policy associated with that role grants your Lambda function access to particular AWS-managed services or infrastructure (Create Logs, Access DynamoDB, send SQS messages, etc.).
- Amazon API Gateway Lambda function invocation permission– Amazon API Gateway cannot invoke your Lambda function without explicit permission to do that. You must grant this permission via the permission policy associated with the Lambda function or with invocation credentials (an IAM role) assigned to the API Gateway when invoking a particular function.
You can grant API Gateway Lambda function invocation permissions using one of the following 3 approaches: AWS Console, CLI, and Swagger file.
AWS Console
When you specify Lambda function as API Gateway backend or custom authorizer, AWS Console informs you that the API Gateway needs permission in order to invoke that Lambda function. If you confirm that you agree with the permission requested, AWS Console automatically creates and assigns an appropriate policy. You cannot see this policy in the AWS Console. It is also not available when you export API as a Swagger file.
AWS CLI
With AWS CLI you can directly define the permission by adding it to Lambda’s policy:
The only way to see these permissions is by executing the following CLI command:
Swagger
The third way to assign Lambda invocation permissions to the API Gateway is by specifying an appropriate role in the Swagger API definition file.
For the custom authorizer, you must include the authorizerCredentials property,
where lambdaFunctionIAMRole is a custom IAM Role that has trusted relationship with apigateway.amazonaws.com:
If you do not specify authorizerCredentials in the Swagger API definition file, AWS API Gateway does not automatically add permission to Lambda’s function policy.
The same IAM Role can be used for allowing API Gateway access to the backend Lambda functions. In this particular case, the Swagger file shall be modified by adding the credentials property in the resource’s integration request definition section:
Conclusion
When you create AWS API Gateway API that uses Lambda functions as backend or custom authorizers, you need to think about policies and permissions that allow API Gateway Lambda function invocation.
If you are using the AWS Console, these permissions will be created for you automatically. But if you are deploying the API through other mechanisms like AWS CLI, Cloud Formation, etc., you must be aware of these permissions and define them manually as explained in this article.
Useful links
Read more about API Gateway at official AWS documentation:
http://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started.html
AWS API Gateway custom authorizers are explained at:
http://docs.aws.amazon.com/apigateway/latest/developerguide/use-custom-authorizer.html
Details about Swagger, writing, and documenting API are available at:
