Which TLS versions does Cosmo Router support?

TLS 1.0, 1.1, 1.2, and 1.3 are supported, inheriting Go's TLS library defaults. TLS 1.2 or higher is strongly recommended for production deployments.

Does TLS enable HTTP/2 automatically?

Yes. When TLS is enabled, HTTP/2 is automatically available. Clients that support HTTP/2 are upgraded. No additional configuration is required to benefit from multiplexing and header compression.

What file format is required for certificates?

PEM format is required for both the certificate and key files. Both cert_file and key_file must be provided to enable TLS.

How does mTLS differ from standard TLS?

Standard TLS verifies the server's certificate. mTLS (mutual TLS) additionally requires the client to present a certificate that the server validates. Enable mTLS by setting client_auth.cert_file and client_auth.required: true. Connections without valid client certificates are then refused.

Does TLS apply to subgraph connections?

Yes, for HTTP subgraphs. When subgraph URLs use the https:// scheme, the router connects over TLS automatically. gRPC subgraphs (Cosmo Connect) use a separate tls.client_grpc configuration and require enabled: true — an https:// URL alone does not enable TLS for them.

Which router version is required?

TLS support is available since Router version 0.71.0.

TLS and mTLS for GraphQL | Cosmo by WunderGraph

The problem

Unencrypted internal traffic is a gap most teams accept

Traffic inside an infrastructure perimeter often travels in plaintext. mTLS is skipped because the setup is complex. HTTP/2 goes unused because enabling it requires TLS first.

Plaintext traffic is interceptable inside the perimeter

Traffic between a load balancer and the router often travels unencrypted within the infrastructure. Any compromised node on that path can read or modify the data in transit.

Mutual authentication requires complex custom setup

mTLS — where both client and server present certificates — requires coordinating certificate authorities, key files, and Go TLS config. Most teams skip it and accept the risk.

HTTP/2 is blocked without TLS

HTTP/2 multiplexing and header compression improve performance at scale, but TLS is mandatory for HTTP/2 operation. No TLS means no HTTP/2.

Our solution

TLS in YAML, HTTP/2 for free

Enable TLS with a cert and key file path. HTTP/2 follows automatically. Add a client_auth block for mTLS. No code changes, no middleware.

From plaintext to encrypted in six steps

Add the tls.server block to router YAML with cert_file and key_file paths pointing to PEM-format files.
The router starts an HTTPS listener. All client connections are encrypted.
HTTP/2 is automatically available when TLS is enabled. Clients supporting HTTP/2 are upgraded automatically.
For subgraph connections, use HTTPS URLs in the subgraph configuration. The router connects over TLS automatically.
For mTLS, add client_auth.cert_file with the CA certificate for validating client certificates.
Set client_auth.required: true to enforce that every client must present a valid certificate. Connections without valid certificates are refused.

Available since Router 0.71.0.

TLS / HTTPS

Before & After

Before Cosmo	With Cosmo
Plaintext traffic between load balancer and router	TLS encryption for all client connections
Manual TLS configuration with custom code	cert_file and key_file in YAML, no code changes
HTTP/2 requires separate configuration	HTTP/2 automatic when TLS is enabled
mTLS requires complex setup and coordination	client_auth block with required: true in YAML

Protocol support

Go TLS defaults, all modern ciphers

Cipher suites follow Go TLS defaults: ECDHE with AES-GCM, ChaCha20-Poly1305, and CBC. TLS 1.0 through 1.3 supported. WunderGraph strongly advises against TLS below 1.2.

TLS 1.0TLS 1.1TLS 1.2TLS 1.3ECDHE-ECDSAECDHE-RSAChaCha20-Poly1305AES-128-GCMAES-256-GCMHTTP/2

How TLS works in Cosmo Router

01

Three lines in YAML.

Configure

Add tls.server.enabled: true with key_file and cert_file paths to the router YAML. Both PEM files are required. Available since Router 0.71.0.

02

TLS 1.0–1.3, Go cipher defaults.

Connect

The router listens for HTTPS connections. Client connections are encrypted using Go's standard TLS library. Supports TLS 1.0 through TLS 1.3. Go defaults apply for cipher suites (ECDHE-ECDSA, ECDHE-RSA, ChaCha20-Poly1305, AES-GCM).

03

HTTP/2 at no extra config cost.

Upgrade

HTTP/2 becomes available automatically when TLS is enabled. Clients that support HTTP/2 are upgraded. Multiplexing and header compression apply to all upgraded connections.

04

Bidirectional authentication, optional.

Authenticate

For mTLS, add client_auth.cert_file with the CA certificate. By default, clients without certificates are still accepted. Set client_auth.required: true to enforce client certificate validation and refuse connections that fail.

Encryption controls

Every connection, every direction

Client-to-router, router-to-subgraph, and bidirectional with mTLS.

Standard TLS for client connections

Provide cert_file and key_file in PEM format. The router listens for HTTPS connections. No load balancer TLS termination required.

Automatic HTTP/2 upgrade

HTTP/2 is enabled automatically when TLS is on. Clients that support HTTP/2 connect via h2. Multiplexing and header compression are active with no extra configuration.

Mutual TLS (mTLS)

Add client_auth.cert_file with the CA certificate. By default, clients without certificates are still accepted. Set required: true to enforce that every client presents a valid certificate.

Subgraph TLS

Use https:// URLs in subgraph configuration. The router connects to those subgraphs over TLS automatically, using Go's standard TLS client.

Encrypt your router connections

Add tls.server to router YAML. HTTP/2 follows. Add client_auth for zero-trust mTLS.

Start Free Read the Docs

Encrypt every connection to and from the router