diff --git a/docs/router/configuration.mdx b/docs/router/configuration.mdx index 9af6f9c6..a228ac9c 100644 --- a/docs/router/configuration.mdx +++ b/docs/router/configuration.mdx @@ -414,6 +414,34 @@ tls: cert_file: ../your/cert.pem ``` +### Outbound Client TLS (mTLS to Subgraphs) + +Configure TLS client certificates for outbound connections from the router to subgraphs. See [Outbound mTLS to Subgraphs](/router/security/tls#router-mtls) for details. + +| Environment Variable | YAML | Required | Description | Default Value | +| ----------------------------------------- | --------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------- | +| TLS_CLIENT_CERT_FILE | tls.client.all.cert_file | | Path to the client certificate chain file for authenticating the router to subgraphs. | | +| TLS_CLIENT_KEY_FILE | tls.client.all.key_file | | Path to the client private key file. | | +| TLS_CLIENT_CA_FILE | tls.client.all.ca_file | | Path to a custom CA certificate file for verifying subgraph server certificates. | | +| TLS_CLIENT_INSECURE_SKIP_CA_VERIFICATION | tls.client.all.insecure_skip_ca_verification | | Skip verification of the subgraph server certificate. Only use for development or testing. | false | + +### Example YAML config: + +```yaml config.yaml +version: "1" + +tls: + client: + all: + cert_file: /path/to/client.crt + key_file: /path/to/client.key + ca_file: /path/to/ca.crt + subgraphs: + products: + cert_file: /path/to/products-client.crt + key_file: /path/to/products-client.key +``` + ## Compliance The configuration for the compliance. Includes for example the configuration for the anonymization of the IP addresses. diff --git a/docs/router/security/tls.mdx b/docs/router/security/tls.mdx index 6f580d9f..fe62d89a 100644 --- a/docs/router/security/tls.mdx +++ b/docs/router/security/tls.mdx @@ -117,3 +117,61 @@ _, err = client.Do(req) That's it! The router should now be able to receive TLS connections **only** from clients who authenticate themselves using a certificate issued by your trusted CA. +## TLS with Subgraphs + +### Router mTLS + +In addition to accepting mTLS connections from clients (inbound), the router can also present client certificates when connecting to subgraphs (outbound). This is useful when your subgraphs require mTLS authentication to accept requests from the router. + +You can configure a global client certificate that applies to all subgraph connections, and optionally override it on a per-subgraph basis. + +#### Global Configuration + +Apply a client certificate to all outbound subgraph connections: + +```yaml config.yaml +tls: + client: + all: + cert_file: /path/to/client.crt + key_file: /path/to/client.key +``` + +#### Per-Subgraph Configuration + +Override the global config for specific subgraphs. Each entry fully overrides the global `all` config for that subgraph: + +```yaml config.yaml +tls: + client: + all: + cert_file: /path/to/default-client.crt + key_file: /path/to/default-client.key + subgraphs: + products: + cert_file: /path/to/products-client.crt + key_file: /path/to/products-client.key + inventory: + cert_file: /path/to/inventory-client.crt + key_file: /path/to/inventory-client.key +``` + + + Per-subgraph entries live under `tls.client.subgraphs` and use the same field structure as `tls.client.all` (e.g., `cert_file`, `key_file`). A per-subgraph entry fully overrides the global `all` config for that subgraph. + + +### Custom CA Certificates + +By default, the router uses your operating system's root CA store to verify subgraph server certificates. If your subgraphs use TLS certificates signed by an internal or private CA that is not in the system's root CA store, you can provide a custom CA certificate file using `ca_file`. The router will use this CA to verify the subgraph's server certificate during the TLS handshake. + +```yaml config.yaml +tls: + client: + all: + ca_file: /path/to/internal-ca.crt + insecure_skip_ca_verification: false +``` + + + `insecure_skip_ca_verification` disables subgraph certificate validation. Only use this for development or testing environments. +