A JWT Authorizer on an API Gateway doesn’t actually validate the JWT itself; it just passes it along to your backend, trusting you to do the heavy lifting.
Let’s watch a request fly through.
Imagine a user logs in via your application. They send their credentials to a dedicated authentication service. This service, upon successful verification, mints a JSON Web Token (JWT) and sends it back to the user’s browser. This JWT contains claims about the user, like their ID, roles, and an expiration timestamp.
{
"sub": "user123",
"roles": ["admin", "editor"],
"exp": 1700000000
}
Now, when the user wants to access a protected resource on your API Gateway, their browser includes this JWT in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIiwicm9sZXMiOlsiYWRtaW4iLCJjZW50ZXIiXSwiZXhwIjoxNzAwMDAwMDAwfQ.some_signature
You’ve configured your API Gateway with a JWT Authorizer. You’ve told it where to expect the JWT (e.g., Authorization header) and what the issuer (iss) and audience (aud) of the token should be. When a request hits the API Gateway with an Authorization header, the JWT Authorizer component intercepts it.
Crucially, the API Gateway’s JWT Authorizer does not verify the signature of the JWT. It only checks if the token is present, if it matches the expected issuer and audience (if configured), and if it’s not expired. If these basic checks pass, the authorizer allows the request to proceed to your backend. The entire JWT, including its signature, is then passed to your backend service, typically in a special header like x-api-gateway-auth or x-amzn-oidc-data.
Your backend service is responsible for the real security: validating the JWT’s signature against the issuer’s public key and re-verifying the claims (like expiration and issuer/audience).
Here’s a simplified diagram of the flow:
+-----------------+ +-----------------+ +-----------------+ +-----------------+
| User's Browser | ----> | API Gateway | ----> | JWT Authorizer | ----> | Backend Service |
| (Sends JWT) | | (Intercepts) | | (Basic Checks) | | (Full Validation) |
+-----------------+ +-----------------+ +-----------------+ +-----------------+
The Problem This Solves:
This pattern decouples authentication from your core business logic. Your backend services don’t need to know how to interact with every authentication provider; they just need to trust the JWTs presented by the API Gateway after a basic preliminary check. It allows you to manage authentication centrally and scale it independently.
How It Works Internally (API Gateway):
When you configure a JWT Authorizer in AWS API Gateway, you provide:
- Identity Source: The header where the JWT is expected (e.g.,
method.request.header.Authorization). - Issuer: The URL of the authentication server (e.g.,
https://your-auth-provider.com). - Audience: The identifier for your API (e.g.,
api.your-domain.com). - JWKS URI (Optional but Recommended): The URL where the authorizer can fetch the public keys to verify the JWT’s signature. However, many basic JWT Authorizers in API Gateway actually skip this signature verification step and rely on the backend. This is a critical point of confusion. The "JWT Authorizer" often means "token-passing authorizer" where the backend does the heavy lifting.
If you do configure JWKS URI, the API Gateway will fetch the public keys from that URI, cache them, and use them to verify the signature. If it doesn’t have JWKS, it’s essentially just checking for the presence of a token and its basic expiration, issuer, and audience.
The Levers You Control:
- Issuer URL: This dictates who is issuing the tokens. Your API Gateway needs to know this to perform its preliminary checks.
- Audience Value: This ensures the token was intended for your API. Prevents a token issued for one service from being used with another.
- Token Source: Where the API Gateway looks for the token (e.g.,
Authorizationheader, query parameter). - Token Verification (Backend): The actual cryptographic verification of the signature and detailed claim validation is your responsibility in the backend service. Libraries like
jsonwebtoken(Node.js),PyJWT(Python), orjwt-go(Go) are commonly used.
The One Thing Most People Don’t Know:
The API Gateway’s built-in "JWT Authorizer" often acts more like a "token forwarder" than a strict validator, especially if you haven’t configured JWKS URI or if you’re using custom authorizers. It performs some checks (like expiration, issuer, audience presence), but the critical step of verifying the JWT’s signature against the issuer’s public key is frequently offloaded to your backend service. This means your backend must always perform its own robust validation, even if the API Gateway allowed the request through. Trusting the API Gateway implicitly can lead to serious security vulnerabilities.
The next concept you’ll run into is how to securely manage the public keys your backend service uses to verify JWT signatures.