JWT Authentication for Federated GraphQL | Cosmo by WunderGraph - WunderGraph

Authenticate every GraphQL request at the router

JWKS-based JWT validation before requests reach any subgraph. Multiple identity providers, automatic key refresh, and algorithm whitelisting — all in YAML, no code changes in subgraphs.

Compatible with any OAuth 2.0 or OpenID Connect identity provider.

The problem

Distributed authentication is hard to keep consistent

When every subgraph validates tokens independently, policies drift, key rotation breaks services, and supporting multiple providers requires duplicated code.

Each subgraph validates tokens differently

One team uses a library pinned to an old version. Another rolls custom validation. Policies diverge silently across services.

Key rotation causes service interruptions

When a signing key rotates, subgraphs with cached public keys begin rejecting valid tokens until they refresh — with no coordinated handling across services.

Supporting multiple identity providers multiplies the code

A SaaS platform serving enterprise customers with separate Okta, Auth0, and Azure AD tenants needs per-provider validation logic in every service.

Our solution

One authentication point for the entire graph

The router validates JWTs from every configured identity provider before a request reaches any subgraph. Subgraphs receive authenticated requests — they do no token validation themselves.

End-to-end authentication flow

Configure one or more JWKS endpoints in the router YAML.
The router extracts tokens from the Authorization header by default. Additional header sources and custom prefixes are configurable.
For each request, the router validates the token against cached JWKS keys, checks the algorithm against the configured allowlist, and optionally validates audience claims.
Validated claims are made available to the request pipeline, including authorization directives and custom modules.
Missing tokens allow anonymous access by default. Set authorization.require_authentication: true to reject unauthenticated requests with 401.
The router keeps JWKS cached and refreshes on a configurable schedule. Unknown Key IDs trigger on-demand refresh with rate limiting.

Requires Router 0.60.0+ for authorization directive support.

Before & After

Before Cosmo	With Cosmo
Token validation logic duplicated in each subgraph	Single JWKS validation point at the router
Key rotation requires coordinated deploys across services	Automatic JWKS refresh with configurable intervals
Multiple identity providers require custom code per service	Multiple JWKS endpoints configured in one YAML block
Token format assumptions baked into each service	Configurable header name, prefix, and additional sources

Multiple JWKS endpoints, one block

Each JWKS endpoint has its own refresh_interval, algorithms allowlist, and optional audiences. Symmetric algorithms configure a secret instead of a URL. Providers are tried in definition order.

How JWT authentication works in Cosmo Router

Configure

Add JWKS endpoints to router YAML. Each endpoint accepts a URL, refresh interval, algorithm allowlist, and optional audience claims. Symmetric algorithms (HS256, HS512) use a secret instead of a URL.

Extract

The router pulls the token from the Authorization header (Bearer prefix by default). Additional headers and custom prefixes are configurable via header_sources. The scope claim defaults to "scope" and is configurable via scope_claim.

Validate

The router tries each configured provider in order. The first provider that validates the token wins. Signature, algorithm, and audience are checked. Invalid tokens return 403 Forbidden.

Refresh

JWKS keys are cached and refreshed on schedule. When the router encounters a token with an unknown Key ID, it fetches updated JWKS immediately, rate-limited by burst, interval, and max_wait settings.

Every auth scenario, handled

From standard OIDC to key rotation and multi-tenant SaaS.

Multiple JWKS endpoints

Configure any number of providers. Each has its own URL, refresh interval, algorithm allowlist, and optional audience validation. Providers are tried in definition order.

Automatic key refresh

JWKS keys are cached and refreshed on a configurable schedule. Enable refresh_unknown_kid to fetch updated keys on demand when a token presents an unknown Key ID.

Symmetric algorithm support

HS256 and HS512 are supported via a shared secret configured in YAML. Use this for internal services where asymmetric keys are not needed.

Flexible token extraction

The default header is Authorization with a Bearer prefix. Configure additional header_sources with custom header names and value prefixes. Configure scope_claim for non-standard scope field names.

Add JWT authentication to your router

Configure JWKS endpoints in router YAML. Authentication enforced at the router, no changes in subgraphs.

FAQ

JWT Authentication on Cosmo Router

Can the router authenticate against multiple identity providers?
What happens when a token is missing?
How does the router handle key rotation?
Which JWT algorithms are supported?
Can I bypass authentication for introspection queries?
Are authentication headers forwarded to subgraphs?

Full reference in the authentication documentation.