Choosing an API Gateway authorizer

Using AWS Security for Developers

Rahul Singh

Technical Product Manager

Checked before your code runs

A caller passes through the API Gateway authorizer before reaching your code, and a rejected caller is turned away with a 401.

Pass: the request reaches your code

Fail: 401 unauthorized, your code never runs

Who does the checking

Three authorizers to choose from

IAM auth (AWS_IAM): AWS checks a signature

A vertical stack on an axis running from AWS doing the checking down to you doing it. Only the first card is filled in: IAM auth, where AWS checks a signature.

Who does the checking

Three authorizers to choose from

IAM auth (AWS_IAM): AWS checks a signature
Cognito authorizer (COGNITO_USER_POOLS): AWS verifies a token
- Signature, iss, aud, exp

The same vertical stack with two cards filled in: IAM auth, where AWS checks a signature, and a Cognito authorizer, where AWS verifies a token.

Who does the checking

Three authorizers to choose from

IAM auth (AWS_IAM): AWS checks a signature
Cognito authorizer (COGNITO_USER_POOLS): AWS verifies a token
- Signature, iss, aud, exp
Lambda authorizer: your function returns allow or deny
- For tokens that are not Cognito

Three authorizers ranked from AWS doing the checking to you doing it: IAM auth where AWS checks a signature, a Cognito authorizer where AWS verifies a token, and a Lambda authorizer where you write the check.

Match the door to the caller

The caller decides

Internal service: holds AWS credentials already

The first of three caller-to-authorizer rows: an internal service mapped to IAM auth.

Match the door to the caller

The caller decides

Internal service: holds AWS credentials already
App user: carries a Cognito token

Two of three caller-to-authorizer rows: an internal service mapped to IAM auth, and an app user mapped to a Cognito authorizer.

Match the door to the caller

The caller decides

Internal service: holds AWS credentials already
App user: carries a Cognito token
Partner app: brings its own authorization logic

Three callers mapped to the authorizer each one needs: an internal service to IAM auth, an app user to a Cognito authorizer, and a partner app to a Lambda authorizer.

Mind the API type

REST API

All three authorizers, plus resource policies
API keys, per-client throttling, request validation, WAF

A comparison card for a REST API, ticking IAM auth, a Cognito user pool authorizer, a Lambda authorizer, and a resource policy. The HTTP API card beside it is not yet filled in.

Mind the API type

REST API

All three authorizers, plus resource policies
API keys, per-client throttling, request validation, WAF

HTTP API

JWT authorizer, any OIDC issuer
No resource policies; cheaper and faster

Two cards comparing which authorizers each API type supports: a REST API adds resource policies, while an HTTP API swaps the Cognito authorizer for a JWT authorizer and has no resource policies.

The authorizer remembers

Cached to save time

First call: the authorizer runs
Later calls: read the cached answer

The first call runs the authorizer and writes an allow into a cache with a time to live, and a later call reads that allow from the cache without running the authorizer again.

The authorizer remembers

Cached to save time

First call: the authorizer runs
Later calls: read the cached answer

Cache TTL

authorizerResultTtlInSeconds: 300s default, 3600s max
Zero disables caching

The first call runs the authorizer and writes an allow into a cache with a time to live, and a later call reads that allow from the cache without running the authorizer again.

A cached allow can outlive its permission

A two-lane timeline. The permission lane changes from valid to revoked at the revoke point, while the cached allow lane below still shows allow past that point, with the window after revocation shaded.

At the moment you revoke

Permission: revoked at once
Cached allow: still granting

A cached allow can outlive its permission

The same two-lane timeline with the window between the revoke point and TTL expiry shaded and marked still allowed, where the permission is revoked but the cached allow keeps granting access.

The window in between

Permission gone, cache not told
Access lasts until the TTL expires

A cached allow can outlive its permission

The same two-lane timeline with an arrow across the shaded window showing that a shorter TTL moves expiry earlier and shrinks the span where a revoked permission still grants access.

Control that window

Short TTL when revocation must be fast
TTL 0 on the most sensitive routes

One caller skips the front door

A third party inside your account

Assumes a role you created
You hand over the role ARN

A monitoring vendor sits between two customer boxes above and your role below. Your box hands its role ARN down to the vendor, which assumes your role. The second customer box is grayed out and not yet part of the story.

One caller skips the front door

A third party inside your account

Assumes a role you created
You hand over the role ARN

The role ARN is not a secret

The confused deputy problem

The second customer box is now active in red and hands over your role ARN as if it were its own. Two arrows now run from the monitoring vendor down to your role, one call per customer, and nothing distinguishes them.

One caller skips the front door

A third party inside your account

Assumes a role you created
You hand over the role ARN

The role ARN is not a secret

The confused deputy problem

The fix: sts:ExternalId

The vendor generates one per customer
Your trust policy requires the match

Your role now carries a requirement that the external ID equal 12345. The call carrying 12345 reaches the role, and the call carrying 99999 is stopped by a red cross before it arrives.

Let's practice!

Using AWS Security for Developers