Skip to content

tls.mdx

Latest commit

 

History

History
139 lines (101 loc) · 4.87 KB

tls.mdx

File metadata and controls

139 lines (101 loc) · 4.87 KB
title TLS
subtitle Secure client-side and subgraph-side communications
redirectFrom
/router/configuration/overview/#tls

import RedisTls from '../../../shared/redis-tls.mdx';

The GraphOS Router supports TLS to authenticate and encrypt communications, both on the client side and the subgraph side. It works automatically on the subgraph side if the subgraph URL starts with https://.

tls:
  supergraph:
    certificate: ${file./path/to/certificate.pem}
    certificate_chain: ${file./path/to/certificate_chain.pem}
    key: ${file./path/to/key.pem}

Configuring TLS

TLS support is configured in the tls section, under the supergraph key for the client side, and the subgraph key for the subgraph side, with configuration possible for all subgraphs and overriding per subgraph.

The list of supported TLS versions and algorithms is static.

Supported TLS versions

  • TLS 1.2
  • TLS 1.3

Supported TLS cipher suites

  • TLS13_AES_256_GCM_SHA384
  • TLS13_AES_128_GCM_SHA256
  • TLS13_CHACHA20_POLY1305_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

Supported key exchange groups

  • X25519
  • SECP256R1
  • SECP384R1

TLS termination

Clients can connect to the router directly over HTTPS, without terminating TLS in an intermediary. You can configure this in the tls configuration section:

tls:
  supergraph:
    certificate: ${file./path/to/certificate.pem}
    certificate_chain: ${file./path/to/certificate_chain.pem}
    key: ${file./path/to/key.pem}

To set the file paths in your configuration with Unix-style expansion, you can follow the examples in the variable expansion guide.

The router expects the file referenced in the certificate_chain value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).

Overriding certificate authorities for subgraphs

The router verifies TLS connections to subgraphs using the list of certificate authorities the system provides. You can override this list with a combination of global and per-subgraph settings:

tls:
  subgraph:
    # Use these certificate authorities unless overridden per-subgraph
    all:
      certificate_authorities: "${file./path/to/ca.crt}"
    # Override global setting for individual subgraphs
    subgraphs:
      products:
        certificate_authorities: "${file./path/to/product_ca.crt}"

The router expects the file referenced in the certificate_chain value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).

You can only configure these certificates via the router's configuration since using SSL_CERT_FILE also overrides certificates for sending telemetry and communicating with Apollo Uplink.

If the subgraph is presenting a self-signed certificate, it must be generated with the proper file extension and with basicConstraints turned off. You can generate it with the following command line command from a certificate signing request, in this example, server.csr:

openssl x509 -req -in server.csr -signkey server.key -out server.crt -extfile v3.ext

You can generate a v3.ext extension file like so:

subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer:always
# this has to be turned off
# basicConstraints       = CA:TRUE
keyUsage               = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign
subjectAltName         = DNS:local.apollo.dev
issuerAltName          = issuer:copy

Make sure to change the subjectAltName field to the subgraph's name.

This produces the file as server.crt which can be used in certificate_authorities.

TLS client authentication for subgraph requests

The router supports mutual TLS authentication (mTLS) with the subgraphs. This means that it can authenticate itself to the subgraph using a certificate chain and a cryptographic key. It can be configured as follows:

tls:
  subgraph:
    # Use these certificates and key unless overridden per-subgraph
    all:
      client_authentication:
        certificate_chain: ${file./path/to/certificate_chain.pem}
        key: ${file./path/to/key.pem}
    # Override global setting for individual subgraphs
    subgraphs:
      products:
        client_authentication:
          certificate_chain: ${file./path/to/certificate_chain.pem}
          key: ${file./path/to/key.pem}

Redis TLS configuration

Nest this tls configuration under the redis key for your feature, for example, under apq.router.cache for APQ caching.