[AS-184] Tech note: Router auth with JWT + SigV4 on AWS

[ilan-bel]

Summary

Adds docs/router-aws-jwt-sigv4.md covering the two auth patterns Apollo Router needs on AWS:

• JWT at the edge — validating inbound Bearer tokens against Cognito / Auth0 / OIDC JWKS endpoints, with Cognito-specific gotchas (access vs id tokens, regional JWKS URLs, token TTL).
• SigV4 to subgraphs — signing outbound requests so Router can call IAM-authenticated API Gateway, Lambda Function URLs, AppSync, and App Runner using IRSA / ECS task role / EC2 instance profile.

Includes a combined router.yaml example with a header rule that strips the inbound Authorization header before SigV4 signing, plus smoke-test guidance.

Note

Originally drafted as a TN for apollographql/docs. That repo is now archived; the new apollographql/platform-docs requires SAML SSO grant on the contributor's OAuth token. Landing in apollosolutions/reference-architecture/docs/ as an interim home; can be migrated upstream once the SSO grant is in place.

Tracks AS-184.

Test plan

• Markdown renders cleanly on github.com
• All https://www.apollographql.com/docs/... links resolve
• Code blocks are syntactically valid YAML

🤖 Generated with Claude Code

[apollo-solutions-reviewer]

Solid tech note; the Cognito access-vs-id-token guidance, the IRSA/ECS/EC2 credential-chain breakdown, and the strip-Authorization-before-SigV4 header rule are all accurate and genuinely useful. A few blocking issues against the AS-184 acceptance criteria before this is ready.

1. Invalid JWKS config key. In the Pattern 1 snippet the JWKS entry uses issuer: (singular scalar). The Router JWT plugin option is issuers: (a list); see https://apollographql.com/docs/graphos/routing/security/jwt#configuration-options. As written this YAML will fail config validation, which conflicts with the AC "working YAML snippets" and the PR's own "validated against a current Router version" test-plan item. Use issuers: ["https://cognito-idp.${AWS_REGION}.amazonaws.com/${USER_POOL_ID}"].

2. Documentation links point at the archived IA. Every https://www.apollographql.com/docs/router/configuration/... link (and its anchors: #token-claims, #renewing-tokens, #requiresscopes, #policy) targets the pre-migration Router docs path. The current IA places these under /docs/graphos/routing/...: JWT at graphos/routing/security/jwt, SigV4 at graphos/routing/security/subgraph-authentication, authorization at graphos/routing/security/authorization. Since the ticket is explicitly motivated by the new docs IA and the test plan's "all links resolve" box is unchecked, please repoint all internal links and re-verify the anchors exist on the new pages.

3. Missing architecture diagram. AC requires a diagram illustrating the client -> Router -> AWS-backed subgraph auth flow. The doc currently has none. A simple Mermaid sequence/flow diagram inline would satisfy this.

4. SE/SA technical review. AC requires sign-off from at least one SE/SA. No review is recorded on the PR yet; please capture that before merge.

Non-blocking nits:

• Pattern 1 mixes the authorization.directives.enabled block with require_authentication; confirm both keys are intended together and match the current authorization config schema on the new page.
• "GA in 2.x" / "Router 1.43+" version claim for the SigV4 plugin should be spot-checked against release notes, since version strings drift.
• CI is green (CLA signed, secrets scan passed); the failures above are content, not pipeline.

[apollo-solutions-reviewer]

issuer: is not a valid JWKS key. The Router option is issuers: and takes a list. As written this fails config validation. Use issuers: ["https://cognito-idp.${AWS_REGION}.amazonaws.com/${USER_POOL_ID}"]. Ref: https://apollographql.com/docs/graphos/routing/security/jwt#configuration-options

[apollo-solutions-reviewer]

Confirmed at head 7adb688: Pattern 1 now uses issuers: as a list with the Cognito issuer URL, so the snippet passes config validation. Resolving.

[apollo-solutions-reviewer]

This and the other /docs/router/configuration/... links use the archived docs path. The current IA serves JWT auth at graphos/routing/security/jwt. Please repoint every internal link (and verify the deep-link anchors) to the new /docs/graphos/routing/... structure; the ticket is specifically about the new IA.

[apollo-solutions-reviewer]

Confirmed at head 7adb688: all internal links now point at /docs/graphos/routing/... (jwt, subgraph-authentication, authorization) with valid anchors; no archived /docs/router/configuration/ paths remain. Resolving.

[apollo-solutions-reviewer]

Re-reviewed at head 7adb688. Two of the four blocking findings are fixed and their threads are resolved:

1. JWKS config: Pattern 1 now uses issuers: as a list; the snippet validates.
2. Doc links: all internal links repointed to /docs/graphos/routing/... (jwt, subgraph-authentication, authorization) with correct anchors; no archived /docs/router/configuration/ paths remain.

Two blocking AC items are still outstanding:

3. Architecture diagram. The AC requires a diagram of the client -> Router -> AWS-backed subgraph auth flow. The current file has none; a Mermaid sequence or flow diagram inline would satisfy this.
4. SE/SA technical review. The AC requires sign-off from at least one SE/SA. The only review on the PR is this bot's; no human SE/SA review is recorded yet.

Add the diagram and capture an SE/SA review, then re-request and I will approve.

[ilan-bel]

@andywgarcia Assigning to you — architecture diagram has been added (satisfying AC item 3), but this still needs SE/SA technical review (AC item 4) before it can be approved. Could you take a look or find an SE/SA to sign off?