feat(auth): add JWT verification and OAuth client credentials

[bfreiberg]

Add JWT verification, coordinated JWKS caching, API Gateway authorization, and OAuth client credentials with optional dependencies, documentation, examples, and tests.

Include exception-safe claims cleanup, sanitized provider errors, and lazy imports for OAuth-only clients and static-key verification.

Issue number: closes #8466

Summary

Changes

• Add strict asymmetric JWT verification with mandatory issuer, resource audience, and expiration checks; additive claim requirements; static keys; OIDC discovery; and coordinated JWKS refresh with maximum age, unknown-key cooldown, and failure backoff.
• Add resource-bound Cognito access-token verification, explicit multi-issuer composition, initialization prefetch, and a testing helper.
• Integrate with Event Handler middleware and REST/HTTP API Gateway authorizers, including scope checks, exception-safe claims cleanup, sanitized errors, opt-in scalar context, and policies restricted to the current request.
• Add OAuth client credentials using client_secret_basic, per-resource token caches, callable secrets, coordinated acquisition, bounded retries, and authenticated HTTPS requests.
• Load the public classes independently so OAuth-only functions avoid JWT/cryptography imports, and static-key verifiers avoid loading HTTP transport. Public imports, introspection, and verification behavior are preserved.
• Add 236 functional tests and 15 local HTTPS integration tests, API documentation, usage examples, and REST/HTTP SAM authorizer configuration with result caching disabled.
• Declare PyJWT, cryptography, and urllib3 as optional dependencies, update the lock file, and add dependency-isolation coverage.

User experience

Applications configure the issuer, resource audience, and permitted algorithms, then use verify() directly, attach require() to a route, or return authorize() from a Lambda authorizer. Outbound clients use auth_headers() with their own HTTP client or call request() for a separate downstream resource.

verifier = JWTVerifier(
    issuer="https://idp.example.com/",
    audience="https://orders.example.com",
    algorithms=["RS256"],
    required_claims=["sub"],
)

@app.get("/orders", middlewares=[verifier.require(scopes=["orders:read"])])
def orders():
    return {"subject": app.context["claims"]["sub"]}

Validation

Check	Result
Full non-performance regression suite, excluding AWS end-to-end tests	2,821 passed; 4 existing skips; 96.53% package coverage
Existing local performance suite	10 passed on the latest run; earlier timing variability is noted below
New Auth suite	251 passed on Python 3.10, 3.12, and 3.14, including 15 HTTPS integration tests and 5 fresh-process import checks
AWS deployment validation before import optimization	104 deployed checks passed on Python 3.12, x86_64 and arm64, in us-east-1
Lambda import-optimization comparison	600 cold and 600 warm invocations across 60 configurations; results below
Dependency isolation	Auth-extra and base-only Nox sessions passed
Static analysis	Ruff formatting/lint, mypy, ty, Bandit baseline, and Xenon complexity baseline passed
Documentation and deployment syntax	MkDocs build, Markdownlint, and cfn-lint passed
Packaging and secrets	Wheel/sdist build, optional-dependency metadata, TOML, diff checks, and Gitleaks passed
MCP example	SDK 2.2.0 server initialization, signed-token mapping, and invalid-token denial verified

Functional tests use real asymmetric signatures and in-memory HTTP endpoints, without external services. They cover expiration and key removal, failed refresh, concurrent acquisition, async thread offloading during initial fetch/expiry/rotation, Cognito token purpose and resource binding, authorizer event fixtures, scope precedence, secret rotation, retry limits, and error redaction.

Regression tests exercise an unhandled protected handler followed by public, denied, and authenticated invocations, verifying that claims never survive the failed request. Error tests inspect __context__, __cause__, rendered tracebacks, and Powertools Logger output for public verification, prefetch, authorizer, and OAuth operations, including failing secret loaders invoked inside an existing exception handler.

Fresh-process tests block JWT/cryptography imports while constructing an OAuth client, and block urllib3 while verifying valid and invalid signatures against static JWKS. They also check that remote-cache construction loads the transport and that public exports retain introspection, unknown-attribute errors, and star-import behavior. Four of these checks failed before the optimization; all five pass afterward.

HTTPS integration tests run the production urllib3 transport against a loopback TLS server with a generated test certificate. They verify discovery/JWKS retrieval, signed-token verification, token exchange and downstream authentication, untrusted-certificate rejection before credentials are sent, response-size limits, stalled and slowly arriving bodies, separate downstream timeouts, and redirect/retry behavior.

Additional deployment checks used the SAM example with temporary AWS-hosted HTTPS fixtures. They exercised REST and HTTP Gateway decisions, middleware challenges, disabled authorizer caching, OAuth acquisition/concurrency/downstream requests, exception cleanup, and remote key rotation/removal/outages on both architectures. A real HTTP API $default route supplied a concrete method/path ARN, which the existing IAM helper successfully authorized. All three test stacks were deleted, with resource cleanup independently verified. These checks ran through a standalone harness; they do not represent the entire repository's AWS end-to-end suite or live Cognito/Keycloak interoperability testing.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[sonarqubecloud]

Quality Gate failed

Failed conditions
D Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[bfreiberg]

I reviewed the two SonarCloud findings in verifier.py. They appear to flag intentional parsing before verification:

• Line 257 — get_unverified_header(): reads the header to select a permitted algorithm and signing key. JWTVerifier.verify() then verifies the signature and validates the claims before returning them.
• Line 308 — verify_signature=False: reads iss solely to select an explicitly configured verifier. Unknown issuers are rejected without network requests. The selected verifier performs full verification; the unverified payload is never
  returned to callers.

I reran the verifier and profile tests: 63 passed, including rejection of tampered signatures, tokens signed with another issuer’s key, and unknown issuers.

Could you review these as potential false positives in SonarCloud? The issuer-routing code already documents this behavior; I can add a similar explanation beside the header parsing.