# 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

1.  Configure one or more JWKS endpoints in the router YAML.
2.  The router extracts tokens from the Authorization header by default. Additional header sources and custom prefixes are configurable.
3.  For each request, the router validates the token against cached JWKS keys, checks the algorithm against the configured allowlist, and optionally validates audience claims.
4.  Validated claims are made available to the request pipeline, including authorization directives and custom modules.
5.  Missing tokens allow anonymous access by default. Set `authorization.require_authentication: true` to reject unauthenticated requests with 401.
6.  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](https://cosmo-docs.wundergraph.com/router/authentication-and-authorization).