TLS

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://.

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, it cannot be configured.

Supported TLS versions:

• TLS 1.2

• TLS 1.3

Supported 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:

1tls:
2  supergraph:
3    certificate: ${file./path/to/certificate.pem}
4    certificate_chain: ${file./path/to/certificate_chain.pem}
5    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:

1tls:
2  subgraph:
3    # Use these certificate authorities unless overridden per-subgraph
4    all:
5      certificate_authorities: "${file./path/to/ca.crt}"
6    # Override global setting for individual subgraphs
7    subgraphs:
8      products:
9        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:

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

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

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

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:

1tls:
2  subgraph:
3    # Use these certificates and key unless overridden per-subgraph
4    all:
5      client_authentication:
6        certificate_chain: ${file./path/to/certificate_chain.pem}
7        key: ${file./path/to/key.pem}
8    # Override global setting for individual subgraphs
9    subgraphs:
10      products:
11        client_authentication:
12          certificate_chain: ${file./path/to/certificate_chain.pem}
13          key: ${file./path/to/key.pem}

Redis TLS configuration

For Redis TLS connections, you can set up a client certificate or override the root certificate authority by configuring tls in your router's YAML config file. For example:

1apq:
2  router:
3    cache:
4      redis:
5        urls: [ "rediss://redis.example.com:6379" ]
6        tls:
7          certificate_authorities: ${file./path/to/ca.crt}
8          client_authentication:
9            certificate_chain: ${file./path/to/certificate_chain.pem}
10            key: ${file./path/to/key.pem}