Cosmo Security

Secure your federated graph at every layer

JWT authentication, schema-level authorization, TLS, HMAC config signing, and production hardening — configured in YAML or the schema, enforced at the router, no middleware required.

Start Free Read the Docs

Seven security controls. One router. Zero custom middleware.

Overview

Security controls, built into Cosmo

Cosmo enforces security at the router — the single entry point for every GraphQL request. JWT validation runs before queries reach subgraphs. Authorization directives declared in any subgraph propagate to the federated schema and are evaluated before execution. TLS encrypts client connections, mTLS verifies them.

Every control is configured in the router's YAML file or directly in the GraphQL schema. No separate middleware, no security proxy, no code changes in subgraphs.

Why federation-native security matters

Why teams need router-level security

In a federated graph, each subgraph is its own service. Without centralized enforcement, every team independently implements authentication, authorization, and error handling — with different results. Policy drift, security gaps, and duplicated code follow.

Four problems that emerge when security is left to individual subgraphs.

Authentication scattered across services.

Each subgraph validates tokens with its own logic. One team upgrades the validation library; another does not. The policies diverge silently.

Authorization requirements are invisible.

Field-level access rules live in resolver code. There's no single place to see what a field requires. Auditing means reading every resolver.

Error messages reveal internal structure.

Subgraph error messages often include database errors, internal service names, and stack traces. Clients receive details that expose attack surface.

Configuration integrity is assumed, not verified.

Router configurations specify subgraph URLs and execution rules. Without signatures, a tampered config that redirects traffic to a malicious server goes undetected.

Cosmo enforces all of this at the router. One config, consistent enforcement across every subgraph.

Cosmo Security capabilities

JWT Authentication

JWKS-based JWT validation at the router, before requests reach any subgraph. Configure multiple identity providers, whitelist algorithms per endpoint, and handle key rotation automatically — no custom code in subgraphs.

Free / Pro / Enterprise

Authorization Directives

Declare access requirements directly in the schema with @authenticated and @requiresScopes. The router evaluates directives before query execution. Directives declared in any subgraph propagate automatically to the federated graph.

Free / Pro / Enterprise

Which security capability do you need?

If you are…	Start here
Validating JWTs from an identity provider at the router	JWT Authentication
Enforcing field-level permissions from the schema	Authorization Directives
Encrypting client connections and enabling HTTP/2	TLS / HTTPS
Preventing tampered router configurations from applying	Config Signing
Preparing a router for production deployment	Security Hardening
Hiding the schema from unauthorized clients	Introspection Control
Preventing internal error details from reaching clients	Subgraph Error Propagation

How Cosmo Security compares

	Cosmo Security	Custom middleware	Per-subgraph implementation
Schema-driven authorization	Yes (@authenticated, @requiresScopes)	No	Requires implementation in each resolver
Multi-provider JWKS	Built-in	Custom build	Custom build per service
Config integrity verification	HMAC-SHA256 admission webhook	Requires implementation	N/A
Error detail filtering	Wrapped and pass-through modes	Custom build	Inconsistent per service
Setup complexity	YAML config	Code + deployment	Code per service

Use cases

Security use cases

Real authentication, authorization, and integrity patterns, and the Cosmo capability behind each one.

Multi-provider auth

Authenticate users from three identity providers with one config

Scenario

A SaaS platform serves enterprise customers who each use their own identity provider — Okta, Auth0, and Azure AD. Every team requires tokens from their provider to access the shared GraphQL API.

How Cosmo handles it

Configure three JWKS endpoints in the router. The router tries each provider in order until one validates the token. Claims from the validated token flow to the request pipeline and to authorization directive evaluation.

Outcome

Multi-tenant authentication without custom code. Each enterprise customer authenticates against their own identity provider while the API stays unified.

Field-level RBAC

Salary fields visible to HR only, performance data to managers

Scenario

An HR system spans multiple subgraphs. Basic employee data is readable by all staff. Salary fields require HR permissions. Performance reviews require management or HR admin access.

How Cosmo handles it

Declare @requiresScopes(scopes: [["hr:read"]]) on salary fields and @requiresScopes(scopes: [["management:read"], ["hr:admin"]]) on performance fields. The router evaluates scope requirements before query execution using AND/OR logic.

Outcome

Fine-grained access control from the schema. No authorization code in resolvers. The schema documents what each field requires.

Configuration integrity

Block tampered configs from reaching a production router

Scenario

A router fetches its configuration from a CDN. An attacker modifies the configuration to redirect traffic to a malicious subgraph URL.

How Cosmo handles it

The admission webhook validates subgraph URLs and returns an HMAC-SHA256 signature. The router verifies the signature before applying any configuration. A tampered config produces a hash mismatch and is rejected. The router continues on its last known-good configuration.

Outcome

Tampered configurations never reach the router. The router rejects the modified config and continues serving traffic on the previously validated configuration.

Why teams use Cosmo Security

Enforcement at the router, not scattered across services. Authentication, authorization, and error filtering run once at the router. No duplicated logic across subgraphs. No policy drift.
Schema as the source of truth for access control. Authorization directives declared in a subgraph propagate automatically to the federated schema. Any developer reading the schema sees what each field requires.
Production hardening in YAML, not code. Disable introspection, enable rate limiting, restrict CORS, block non-persisted operations — all in the router config file. No code changes in subgraphs.

Get started

Secure your federated graph today

Start Free Read the Docs