How to Use Lambda Authorizer in AWS API Gateway

Use a Lambda authorizer by creating a Lambda function that verifies incoming requests and returns an IAM policy. Then, attach this Lambda authorizer to your API Gateway method to control access based on your custom logic.

Syntax

A Lambda authorizer is a Lambda function that receives an event with authorization data, processes it, and returns a policy document. The key parts are:

• event: Contains headers, method ARN, and other request info.
• callback: Used to return the authorization response.
• policyDocument: Defines allowed or denied actions.
• principalId: Identifies the user or client.

javascript

exports.handler = async (event) => {
  // Extract token from event.headers.Authorization
  const token = event.headers.Authorization;

  // Validate token (custom logic)
  if (token === 'allow') {
    return generatePolicy('user', 'Allow', event.methodArn);
  } else {
    return generatePolicy('user', 'Deny', event.methodArn);
  }
};

function generatePolicy(principalId, effect, resource) {
  return {
    principalId: principalId,
    policyDocument: {
      Version: '2012-10-17',
      Statement: [{
        Action: 'execute-api:Invoke',
        Effect: effect,
        Resource: resource
      }]
    }
  };
}

Example

This example shows a Lambda authorizer that allows requests with the token 'allow' and denies others. It returns an IAM policy to API Gateway to permit or block access.

javascript

exports.handler = async (event) => {
  const token = event.headers.Authorization || '';

  if (token === 'allow') {
    return generatePolicy('user123', 'Allow', event.methodArn);
  } else {
    return generatePolicy('user123', 'Deny', event.methodArn);
  }
};

function generatePolicy(principalId, effect, resource) {
  return {
    principalId: principalId,
    policyDocument: {
      Version: '2012-10-17',
      Statement: [{
        Action: 'execute-api:Invoke',
        Effect: effect,
        Resource: resource
      }]
    }
  };
}

Output

{"principalId":"user123","policyDocument":{"Version":"2012-10-17","Statement":[{"Action":"execute-api:Invoke","Effect":"Allow","Resource":"arn:aws:execute-api:region:account-id:api-id/stage/GET/resource"}]}}

Common Pitfalls

• Not returning a valid policy document causes API Gateway to reject requests.
• Forgetting to include principalId breaks user identification.
• Using synchronous callbacks instead of async/await can cause timeouts.
• Not attaching the Lambda authorizer to the API Gateway method properly.

javascript

/* Wrong: Missing principalId and invalid policy */
exports.handler = async (event) => {
  return { statusCode: 401 };
};

/* Right: Return full policy with principalId */
exports.handler = async (event) => {
  return {
    principalId: 'user',
    policyDocument: {
      Version: '2012-10-17',
      Statement: [{
        Action: 'execute-api:Invoke',
        Effect: 'Allow',
        Resource: event.methodArn
      }]
    }
  };
};

Quick Reference

• Lambda Authorizer: Custom Lambda function to authorize API Gateway requests.
• Input: Event with headers and method ARN.
• Output: IAM policy with Allow or Deny.
• Attach: Link Lambda authorizer to API Gateway method.
• Test: Use valid tokens to allow access.

Key Takeaways

Create a Lambda function that returns an IAM policy with Allow or Deny effect based on your logic.

Attach the Lambda authorizer to your API Gateway method to control access.

Always return a valid policy document including principalId to avoid errors.

Test your authorizer with different tokens to verify access control.

Use async/await in your Lambda authorizer for reliable execution.