API Gateway Lambda Authorizers and JWT Authorizers

API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at scale. When you expose an API, you need to control who can invoke your endpoints. API Gateway offers several mechanisms for authentication and authorization: IAM roles and policies, Cognito User Pools, Lambda Authorizers (formerly known as Custom Authorizers), and JWT Authorizers. The SAA-C03 exam focuses on the latter two: Lambda Authorizers and JWT Authorizers, especially in the context of HTTP APIs (which are newer and simpler than REST APIs).

JWT Authorizers are a lightweight, low-latency option for APIs that use JSON Web Tokens (JWTs) issued by a trusted identity provider (IdP) such as Auth0, Okta, or Amazon Cognito. The authorizer simply validates the JWT signature, expiry, issuer, and audience. It does not execute any custom code. It is ideal for scenarios where you need simple token-based authentication and your authorization logic is limited to claims within the token.

Lambda Authorizers are more flexible. You write a Lambda function that receives the token or request context and returns an IAM policy that determines whether the request is allowed or denied, and optionally what resources are accessible. This allows you to implement custom logic, such as checking against a database, calling external services, or using complex rules. Lambda Authorizers can be used with both REST APIs and HTTP APIs.

#### JWT Authorizer Mechanism

When a client sends a request to an API Gateway endpoint protected by a JWT Authorizer, the following steps occur:

- Verifying the token signature using the public key from the issuer's JWKS (JSON Web Key Set) endpoint. The issuer is specified in the authorizer configuration (e.g., https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx). - Checking the exp (expiration) claim to ensure the token has not expired. - Validating the iss (issuer) claim matches the configured issuer. - Validating the aud (audience) claim matches the configured audience (for REST APIs, this is optional; for HTTP APIs, it is required). 4. If validation succeeds, the request is forwarded to the backend integration, and the claims from the JWT are available to the backend in the $context.authorizer.claims variable. 5. If validation fails, API Gateway returns a 401 Unauthorized response immediately, without invoking the backend.

Important defaults and limits: - The JWT Authorizer caches the JWKS keys for up to 300 seconds (5 minutes) by default. You cannot change this cache TTL. - The maximum JWT size is 10 KB. - The issuer URL must be HTTPS. - For HTTP APIs, the JWT Authorizer supports only the RS256, RS384, RS512, ES256, ES384, ES512 signature algorithms (asymmetric). It does not support HS256 (symmetric) because that would require API Gateway to know the client secret, which is not secure.

#### Lambda Authorizer Mechanism

A Lambda Authorizer works differently:

- Calling an external OAuth server to introspect the token. - Querying a DynamoDB table to check user permissions. - Decoding a JWT and verifying claims manually. 4. The Lambda function returns a response that includes: - Principal Identifier: A string that identifies the user (optional but recommended). - Policy Document: An IAM policy (similar to an IAM role policy) that specifies Effect (Allow/Deny) and Resource (ARNs of API Gateway methods or stages). The policy can be scoped to specific HTTP methods and paths using the arn:aws:execute-api:{region}:{account-id}:{api-id}/{stage}/{method}/{path} format. - Context: A map of key-value pairs that are passed to the backend integration via $context.authorizer.{key}. This is useful for passing user attributes, roles, or other data. - Usage Identifier Key (for REST APIs only): Used for API keys and usage plans. 5. API Gateway caches the returned policy for a configurable TTL (default 300 seconds, min 0, max 3600). If caching is enabled, subsequent requests with the same token will use the cached policy instead of invoking the Lambda again. 6. If the Lambda function returns an error or times out (default timeout is 30 seconds, but the maximum is 30 seconds for REST APIs and 29 seconds for HTTP APIs), API Gateway returns a 500 Internal Server Error.

Key differences from JWT Authorizers: - Lambda Authorizers can be used with both REST APIs and HTTP APIs, but the event format differs slightly. - Lambda Authorizers allow you to return a policy that grants access to specific resources (e.g., only GET /users, not POST /users). JWT Authorizers only validate the token; the backend must enforce fine-grained authorization. - Lambda Authorizers incur additional cost and latency due to the Lambda invocation.

#### Configuring a JWT Authorizer (HTTP API)

Using the AWS CLI, you can create an HTTP API and attach a JWT Authorizer:

# Create HTTP API
aws apigatewayv2 create-api --name MyHttpApi --protocol-type HTTP

# Create a JWT Authorizer
aws apigatewayv2 create-authorizer \
    --api-id <api-id> \
    --authorizer-type JWT \
    --identity-source '$request.header.Authorization' \
    --name MyJwtAuthorizer \
    --jwt-configuration 'Issuer=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxx,Audience=["myapp"]'

Note: The identity-source specifies where the token is found. The default is $request.header.Authorization. You can also use $request.queryStringParameter.token, etc.

#### Configuring a Lambda Authorizer (REST API)

For REST API:

# Create REST API
aws apigateway create-rest-api --name MyRestApi

# Create Lambda Authorizer
aws apigateway create-authorizer \
    --rest-api-id <api-id> \
    --name MyLambdaAuthorizer \
    --type TOKEN \
    --auth-type CUSTOM \
    --authorizer-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:MyAuthFunction/invocations \
    --identity-source 'method.request.header.Authorization' \
    --authorizer-result-ttl-in-seconds 300

For HTTP API, the command uses apigatewayv2 and the authorizer type is REQUEST (not TOKEN), and the identity source is specified differently.

A company builds a mobile app that uses Amazon Cognito User Pools for user registration and login. The app calls an HTTP API backed by AWS Lambda. They configure a JWT Authorizer on the API Gateway, pointing to the Cognito User Pool as the issuer. The JWT Authorizer validates the access token (or ID token) on every request. This setup is simple, low-latency, and requires no custom code for token validation. In production, they serve millions of requests per day. The main performance consideration is the JWKS cache: API Gateway caches the public keys for 5 minutes, so even if the Cognito User Pool rotates keys, there is a small window where old keys are used. This is acceptable for most use cases. Misconfiguration often occurs when the audience claim is not set correctly: if the app sends an ID token (which has aud set to the app client ID) but the authorizer expects an access token (which has aud set to the resource server), validation fails. The team must ensure they configure the correct token type and audience.

A SaaS provider offers a multi-tenant API where each tenant has custom permissions. They use a Lambda Authorizer to look up the tenant's subscription plan in a DynamoDB table. The authorizer receives the JWT, decodes it to extract the tenant ID, queries DynamoDB, and returns a policy that allows access only to the tenant's specific resources (e.g., /tenant/{tenantId}/*). They set the cache TTL to 60 seconds to quickly reflect changes in subscription status. A common issue is that the Lambda authorizer timeout is too short (default 30 seconds) for complex lookups; they increased it to 29 seconds (max for HTTP API). Another issue is that the policy document size limit is 8 KB; they must keep policies compact. They also use the authorizer context to pass tenant-specific data to the backend Lambda, avoiding extra database calls.

A financial institution uses a REST API with a Lambda Authorizer that integrates with an internal OAuth 2.0 server. The authorizer introspects the token by calling the OAuth server's introspection endpoint. It then returns a policy that restricts access based on the token's scopes. For example, a token with scope read:accounts can only call GET /accounts, while write:accounts allows POST /accounts. The authorizer caches policies for 300 seconds, but for sensitive operations, they set TTL to 0 to force re-evaluation on every request. They also use the authorizer to log all access attempts for auditing. The main challenge is ensuring the Lambda authorizer is highly available and has enough concurrency to handle peak load; they set reserved concurrency on the Lambda function.