Q-Bits: AWS SAM and Custom Authorizers for API Gateway
Amazon Q Developer assisted blog post and AWS SAM based project for exploring API Gateway and custom authorizers.
Troy Parrett
Amazon Employee
Published Mar 25, 2025
Welcome to another installment of Q-Bits, our regular series showcasing cool ways Amazon employees are leveraging Amazon Q Developer. Today, we're diving into how Q Developer can assist with AWS SAM projects, including the use of custom authorizers. For this post, we'll focus mostly on the newly updated CLI with agent functionality. To learn more about that, see this blog post.
Knowing that the goal of my interactions would culminate in a blog post, I decided to actually signal to Q Developer that I wanted a blog post. If I'm going to use AI, I might as well go all-in, no? ;-)
The Q Developer CLI blog post includes specifics on the CLI functionality and great graphics to illustrate, so I won't reiterate that here, but will simply showcase the prompts and the actions that follow afterward.
Hopefully you will see how powerful the agentic nature of the CLI is! In this case to simply bootstrap a project or just to help rapidly create a learning environment to better understand a concept!
Note that I did some minor sanity checking here, including a successful deployment of what was created, however the majority of this content has been machine generated and is for demonstration purposes only!
I started with a prompt similar to the following:
Create a blog post and associated sample project code and commands to AWS SAM: Custom Authorizers for API Gateway - Enhance API security with custom authorizers using SAM. Amazon Q Developer generates SAM templates for Lambda authorizers, explains token-based and request parameter-based authorization, demonstrates caching strategies, and provides examples of integrating with external identity providers.
From there the Q Developer CLI reasoned the need for and created the following artifacts in addition to first creating the directory
`mkdir -p ~/api-gateway-custom-auth-sam/{functions,template,events}`:It also created some nice directions afterward:
Without further ado, the resulting blog!
In today's cloud-native world, securing APIs is a critical concern for developers and organizations. Amazon API Gateway provides a robust platform for creating, publishing, and managing APIs, but implementing proper authorization can be challenging. Custom authorizers offer a flexible solution to this challenge, allowing you to implement complex authorization logic tailored to your specific requirements.
In this blog post, we'll explore how to implement custom authorizers for API Gateway using AWS Serverless Application Model (SAM). We'll cover both token-based and request parameter-based authorization patterns, demonstrate caching strategies, and provide examples of integrating with external identity providers.
Custom authorizers are Lambda functions that control access to your API Gateway endpoints. When a client makes a request to your API, API Gateway invokes your authorizer function before executing the endpoint's integration. The authorizer function evaluates the request and returns an IAM policy that either allows or denies access to the requested resource.
There are two main types of custom authorizers:
- Token-based authorizers: Evaluate a token included in the request, typically in the Authorization header
- Request parameter-based authorizers: Evaluate multiple parts of the request, including headers, query string parameters, and stage variables
- Flexible authentication: Integrate with any identity provider or authentication system
- Fine-grained access control: Implement complex authorization rules based on user attributes, resource types, or other contextual information
- Performance optimization: Cache authorization results to reduce latency and costs
- Separation of concerns: Keep authorization logic separate from your API business logic
- Centralized security: Apply consistent security policies across multiple APIs
Let's start by creating a SAM template that defines our API Gateway with custom authorizers. Our example will include:
- A token-based authorizer for JWT validation
- A token-based authorizer for JWT validation
- A request parameter-based authorizer for API key and query parameter validation
- Protected API endpoints that use these authorizers
- A public endpoint that doesn't require authorization
Token-based authorizers are ideal for validating JWTs (JSON Web Tokens) issued by identity providers like Auth0, Amazon Cognito, or your own custom authentication service.
The token authorizer performs token extraction, validation, an IAM policy document, and passes context.
Request parameter-based authorizers provide more flexibility by allowing you to evaluate multiple parts of the request, including headers, query string parameters, and stage variables.
Some key points about request parameter authorizers:
- Multiple sources: The authorizer can evaluate headers, query parameters, and stage variables.
- Complex Logic: You can implement complex authorization rules based on multiple factors
- Contextual information: You can use stage variables to modify authorization behavior based on deployment stage
- Flexible integration: This approach works well with API keys, custom headers, or query parameters
Authorization checks can add latency to your API calls and increase costs due to additional Lambda invocations. API Gateway allows you to cache authorization results to improve performance.
In our SAM template, we've configured caching for the token authorizer:
- Cache key: For token authorizers, the token itself is used as the cache key
- Cache duration: Set an appropriate TTL based on your security requirements
- Cache invalidation: Consider how to handle revoked tokens or changed permissions
- Cost implications: Caching reduces Lambda invocations but may increase API Gateway costs
Custom authorizers can integrate with various identity providers. Here are some common scenarios:
- Secure secret storage: Store JWT secrets or API keys in AWS Secrets Manager or Parameter Store
- Proper error handling: Return clear but not overly detailed error messages
- Logging and monitoring: Enable CloudWatch logs for debugging and monitoring
- Rate limiting: Implement rate limiting to prevent abuse
- Least privilege: Grant minimal permissions to your authorizer functions
- Testing: Thoroughly test your authorizers with valid and invalid tokens
- Token expiration: Implement and enforce token expiration
- Audit logging: Log authorization decisions for security auditing
Custom authorizers provide a powerful mechanism for implementing flexible and robust authorization for your API Gateway APIs. By leveraging AWS SAM, you can easily define, deploy, and manage these authorizers alongside your API resources.
The examples provided in this blog post demonstrate how to implement both token-based and request parameter-based authorization patterns, optimize performance with caching, and integrate with external identity providers. By following these patterns and best practices, you can enhance the security of your APIs while maintaining flexibility and performance.
Remember that security is a continuous process. Regularly review and update your authorization logic to address new threats and requirements. With custom authorizers, you have the flexibility to adapt your security measures as your application evolves.
JWT.io - Useful for debugging JWTs
AWS Secrets Manager - For storing sensitive credentials
Amazon Cognito - Managed authentication service
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.