How to Use Custom Authorizers with API Gateway HTTP APIs in AWS Serverless Applications

4 min readAug 31, 2024

Are you building a serverless application with AWS Lambda and API Gateway HTTP APIs? Are you facing challenges with:

Implementing complex or custom authentication logic?
Handling different types of tokens or authentication schemes?
Integrating with existing user management systems?
Applying fine-grained access control to your APIs?

Custom authorizers can help solve these problems. In this guide, I’ll explain what custom authorizers are, the specific problems they solve, and how to set them up in your serverless application using the Serverless Framework.

What is a Custom Authorizer?

A custom authorizer is a Lambda function that checks if a request to your API is allowed. It runs before your main API function and decides whether to let the request through or block it.

Key points about custom authorizers:

They are Lambda functions
They run before your main API function
They decide if a request is allowed or not

Problems Solved by Custom Authorizers

Custom authorizers are particularly useful when you need to:

1. Implement complex authentication logic: If you’re using a unique token format or need to perform multiple checks, custom authorizers give you full control.

2. Integrate with external authentication systems: You can easily connect to existing user databases or third-party authentication services.

3. Handle multiple authentication methods: Custom authorizers can manage different types of tokens or authentication schemes within the same API.

4. Apply fine-grained access control: You can implement detailed permission checks based on user roles, scopes, or other attributes.

5. Centralize authorization logic: Instead of implementing auth checks in each Lambda function, you can centralize this in one place.

6. Perform token translation: You can validate one type of token and pass a different format to your backend services.

While custom authorizers are powerful, remember that AWS also offers other security features like Cognito, IAM roles, and API keys. The best choice depends on your specific needs.

Why Use Custom Authorizers?

Custom authorizers offer several benefits:

1. Flexibility: You can use any method to check if a request is allowed.

2. Better Performance: They can cache results, making future checks faster.

3. Separation of Concerns: Keep your security code separate from your main application code.

4. Cost-Effective: You only pay for the time the authorizer runs, not for every API call.

How to Set Up a Custom Authorizer

Let’s look at how to set up a custom authorizer in your serverless.yml file:

provider:
  name: aws
  runtime: nodejs18.x
  httpApi:
    authorizers:
      myCustomAuthorizer:
        type: request
        functionName: myCustomAuthorizer
        identitySource: $request.header.Authorization
        enableSimpleResponses: true
        resultTtlInSeconds: 0

functions:
  myCustomAuthorizer:
    handler: src/auth/customAuthorizer.handler

  getUsers:
    handler: src/users/getUsers.handler
    events:
      - httpApi:
          path: /users
          method: get
          authorizer:
            name: myCustomAuthorizer

Here’s what each part means:

1. We define the authorizer under `provider.httpApi.authorizers`.

2. We set `type: request` to make it a request-based authorizer.

3. `functionName` points to the Lambda function that will do the authorization.

4. `identitySource` tells API Gateway where to find the auth token.

5. `enableSimpleResponses: true` allows for simpler responses from the authorizer.

6. We set `resultTtlInSeconds: 0` to disable caching of results.

We then define the authorizer function and use it in our API endpoints.

Writing the Custom Authorizer Function

Here’s a simple example of a custom authorizer function:

exports.handler = async (event) => {
  const token = event.headers.authorization;

  try {
    // Check if the token is valid
    const user = await checkToken(token);

    return {
      isAuthorized: true,
      context: {
        userId: user.id,
        userRole: user.role
      }
    };
  } catch (error) {
    console.log('Auth failed:', error.message);
    return {
      isAuthorized: false
    };
  }
};

async function checkToken(token) {
  // Add your token checking logic here
  // Return user info if valid, throw an error if not
}

This function does the following:

1. Gets the token from the request headers

2. Checks if the token is valid

3. If valid, it returns `isAuthorized: true` and some user info

4. If not valid, it returns `isAuthorized: false`

Best Practices for Custom Authorizers

When implementing custom authorizers, keep these best practices in mind:

1. Keep it simple: Authorizer functions should be focused solely on authorization.

2. Handle errors gracefully: Provide clear error messages for debugging.

3. Use environment variables: Store sensitive information like secret keys securely.

4. Implement logging: Log enough information to troubleshoot issues, but be careful not to log sensitive data.

5. Consider caching: Use caching to improve performance, but be mindful of cache duration.

Common Pitfalls to Avoid

Watch out for these common mistakes:

1. Over-complicated logic: Keep your authorizer function focused on auth tasks.

2. Insufficient error handling: Ensure you handle all possible error scenarios.

3. Ignoring performance: Be mindful of your authorizer’s execution time.

4. Hardcoding secrets: Use an appropriate approach such as environment variables or secure secret management services rather than hardcoding sensitive information.

Conclusion

Custom authorizers are a powerful way to secure your serverless APIs. They offer flexibility, improved performance, and help keep your code organized. By following this guide, you can easily add custom authorization to your AWS serverless applications using API Gateway HTTP APIs.

Remember to regularly update your authorization logic to keep your APIs secure. Custom authorizers are just one tool in your security toolkit — always consider your specific needs and the full range of AWS security features when designing your application.

Happy coding, and stay secure!