Can the router authenticate against multiple identity providers?

Yes. Configure multiple JWKS endpoints under authentication.jwt.jwks. The router tries them in order; the first successful validation wins. Claims from the validated token flow to the request pipeline.

What happens when a token is missing?

By default, requests without a token are allowed as anonymous. To reject unauthenticated requests, set authorization.require_authentication: true in the router config. Unauthenticated requests then return 401 Unauthorized.

How does the router handle key rotation?

JWKS keys are cached and refreshed at the configured refresh_interval. When the router encounters a valid token with an unknown Key ID, it can fetch updated JWKS immediately if refresh_unknown_kid.enabled is true. Rate limiting (burst, interval, max_wait) prevents overwhelming the JWKS endpoint.

Which JWT algorithms are supported?

The router supports asymmetric algorithms via JWKS endpoints (RS256, EdDSA, and others configured per endpoint) and symmetric algorithms (HS256, HS512) via a shared secret. Specify allowed algorithms per endpoint using the algorithms field.

Can I bypass authentication for introspection queries?

Yes. Set authentication.ignore_introspection: true to skip JWT validation for introspection queries while requiring it for all other operations. Optionally set introspection.secret to require a dedicated secret for introspection access.

Are authentication headers forwarded to subgraphs?

By default, the router does not forward authentication headers to subgraphs. This is configurable via proxy capabilities if your subgraphs need to receive authentication information directly.

JWT Authentication for Federated GraphQL | Cosmo by WunderGraph

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.

JWT Authentication

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

Multi-provider

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.

Multiple JWKS URLsAlgorithm whitelistingAudience validationHS256 / HS512refresh_unknown_kidCustom header sourcesscope_claim override

How JWT authentication works in Cosmo Router

01

Multiple providers, one config block.

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.

02

Flexible token extraction.

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.

03

First match wins. 403 on failure.

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.

04

Zero-downtime key rotation.

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.

Authentication controls

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.

Start Free Read the Docs

Authenticate every GraphQL request at the router