AWS apigateway: Clarify JWT authorizer public key caching and key rotation grace period
Summary
Rewrites step 3 of the HTTP API JWT authorizer workflow to state that API Gateway caches the issuer's public key for up to two hours on a best-effort basis, that cache misses trigger network fetches from the issuer (adding latency, especially for low-traffic APIs), and emphasizes allowing a grace period during key rotation when both old and new keys are valid.
Security assessment
The change documents the caching duration and best-effort nature of JWKS public-key retrieval used to verify JWT algorithm/signature, and reiterates the key-rotation grace-period best practice. This is security-adjacent guidance about authentication (JWT verification) and key rotation hygiene, but it describes no specific vulnerability or incident being fixed, so it is documentation hardening rather than a fix.
Evidence
+ 3. Check the token's algorithm and signature by using the public key that is fetched from the issuer's `jwks_uri`. Currently, only RSA-based algorithms are supported. API Gateway caches the public key for up to two hours on a best-effort basis. On a cache miss, API Gateway fetches the public key from the issuer over the network, which adds latency to the request that triggers it. APIs with a low or intermittent request rate are more likely to experience these fetches. Because a public key can remain cached for up to two hours, allow a grace period when you rotate keys, during which both the old and new keys are valid.
Diff
diff --git a/apigateway/latest/developerguide/http-api-jwt-authorizer.md b/apigateway/latest/developerguide/http-api-jwt-authorizer.md index 1e9e41bbb..4033c79dc 100644 --- a//apigateway/latest/developerguide/http-api-jwt-authorizer.md +++ b//apigateway/latest/developerguide/http-api-jwt-authorizer.md @@ -29 +29 @@ API Gateway uses the following general workflow to authorize requests to routes - 3. Check the token's algorithm and signature by using the public key that is fetched from the issuer's `jwks_uri`. Currently, only RSA-based algorithms are supported. API Gateway can cache the public key for two hours. As a best practice, when you rotate keys, allow a grace period during which both the old and new keys are valid. + 3. Check the token's algorithm and signature by using the public key that is fetched from the issuer's `jwks_uri`. Currently, only RSA-based algorithms are supported. API Gateway caches the public key for up to two hours on a best-effort basis. On a cache miss, API Gateway fetches the public key from the issuer over the network, which adds latency to the request that triggers it. APIs with a low or intermittent request rate are more likely to experience these fetches. Because a public key can remain cached for up to two hours, allow a grace period when you rotate keys, during which both the old and new keys are valid.