Custom Authorizers: The Lambda Bouncer

API Gateway supports three built-in authorization mechanisms: IAM (for AWS service-to-service calls), Cognito User Pools (for user authentication), and native JWT validation (HTTP APIs only). But sometimes none of these fit. You might need to validate a proprietary token format, check a database for session validity, or enforce business rules that depend on request context. For these cases, you use a Lambda Authorizer — a Lambda function that acts as a custom bouncer at the door.

How It Works

When a request arrives, API Gateway intercepts it before routing it to your backend. It invokes your Lambda Authorizer function, passing it the request context. Your Lambda inspects the credentials, makes its decision, and returns an IAM Policy document. API Gateway evaluates that policy and either forwards the request or rejects it with a 403 Forbidden.

{
  "principalId": "user-abc-123",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "execute-api:Invoke",
        "Effect": "Allow",
        "Resource": "arn:aws:execute-api:us-east-1:123456789:abc123/prod/GET/orders"
      }
    ]
  },
  "context": {
    "userId": "user-abc-123",
    "tier": "gold"
  }
}

The context object is passed downstream to your Lambda backend as part of the request context — useful for injecting user metadata without re-parsing the token.

1. Token-Based Authorizer

• Input: A single token, typically extracted from the Authorization header (e.g., Bearer eyJhbGci...).
• Caching: Highly efficient. API Gateway caches the authorization result (Allow/Deny + policy) keyed on the token value, for a configurable TTL (up to 3,600 seconds). If the same token appears 1,000 times in one hour, your Lambda runs once.
• Use Case: Validating JWTs from a third-party identity provider (Auth0, Okta, Firebase) where the token itself contains all necessary claims.

2. Request-Based Authorizer

• Input: The full request context — headers, query string parameters, path parameters, stage variables, and the request body.
• Caching: Difficult to cache effectively because the cache key is constructed from all specified inputs. If any input varies per request, you get a cache miss every time.
• Use Case: Complex authorization logic that depends on multiple request attributes — for example, "Allow only if the X-Client-ID header matches a known partner AND the action query parameter is in the user's permitted set."

The Caching Trade-off

Lambda Authorizer caching is a double-edged sword. A long TTL (e.g., 3,600 seconds) dramatically reduces cost and latency, but means a revoked token remains valid for up to an hour. For high-security APIs (banking, healthcare), use a short TTL (60–300 seconds) or disable caching and accept the Lambda invocation cost. For read-heavy APIs with stable tokens, a long TTL is a significant optimization.

Senior nuance: The IAM policy returned by a Lambda Authorizer can use wildcards in the Resource ARN (e.g., arn:aws:execute-api:*:*:*/*/*/*). This is tempting for simplicity, but it means the cached policy grants access to all methods and stages, not just the one being requested. If a user is authorized for GET /orders, a wildcard policy also grants them DELETE /orders for the duration of the cache TTL. Always scope the Resource ARN to the minimum necessary permissions.