mTLS for Runway Services

Overview

mTLS (mutual Transport Layer Security) is a Runway feature that provides bidirectional authentication between clients and your Runway Services. When enabled, only clients presenting valid, trusted certificates can establish connections to your backend services.

Prerequisites

Before implementing mTLS, ensure you have:

Root CA certificate(s) in PEM format
(Optional) Intermediate CA certificate(s) in PEM format
Vault access to store certificates
Understanding of your certificate chain hierarchy

Process

Store Root CA Certificate(s) in Vault

Store your Root CA certificate(s) in PEM format at the following Vault path:
```
runway/env/<environment>/service/<service-id>/trust_anchor_pem
```
Default Behavior: Runway reads the default_cert key from this secret.

Multiple Root CAs: To use multiple Root CA certificates, specify custom key names in your RunwayService schema:
```
apiVersion: runway/v1
kind: RunwayService
metadata:
  name: your-service-name
spec:
  load_balancing:
    mtls:
      trust_anchor_names:
        - root_ca_primary
        - root_ca_backup
```

Store Intermediate CA Certificate(s) (Optional)

If your certificate chain includes intermediate CAs, store them in Vault at:

runway/env/<environment>/service/<service-id>/intermediate_cas_pem

Update your schema to reference the intermediate certificates:

apiVersion: runway/v1
kind: RunwayService
metadata:
  name: your-service-name
spec:
  load_balancing:
    mtls:
      intermediate_cas_names:
        - intermediate_ca_primary
        - intermediate_ca_secondary

Enable mTLS Configuration

Enable mTLS on either external or internal load balancers:

External Load Balancer:

apiVersion: runway/v1
kind: RunwayService
spec:
  load_balancing:
    external_load_balancer:
      mtls:
        enabled: true
        allow_invalid_or_missing_cert: false

Internal Load Balancer:

apiVersion: runway/v1
kind: RunwayService
spec:
  load_balancing:
    internal_load_balancer:
      mtls:
        enabled: true
        allow_invalid_or_missing_cert: false

Client Validation Options:

allow_invalid_or_missing_cert: false (Recommended): Rejects requests from clients without valid certificates
allow_invalid_or_missing_cert: true: Allows requests from clients with invalid/missing certificates

Configuration Examples

External Load Balancer with Root CA Only

apiVersion: runway/v1
kind: RunwayService
metadata:
  name: secure-api-service
  owner_email_handle: [email protected]
  department: engineering
  department_group: platform
  product_category: api
spec:
  container_port: 8080
  regions:
    - us-east1
    - us-central1
  load_balancing:
    mtls:
      trust_anchor_names:
        - root_ca
    external_load_balancer:
      enabled: true
      mtls:
        enabled: true
        allow_invalid_or_missing_cert: false

Internal Load Balancer with Intermediate CAs

apiVersion: runway/v1
kind: RunwayService
metadata:
  name: internal-service
  owner_email_handle: [email protected]
  department: engineering
  department_group: platform
  product_category: api
spec:
  container_port: 8080
  regions:
    - us-east1
    - us-central1
  load_balancing:
    mtls:
      trust_anchor_names:
        - root_ca
      intermediate_cas_names:
        - intermediate_ca
    internal_load_balancer:
      enabled: true
      mtls:
        enabled: true
        allow_invalid_or_missing_cert: false

Vault Secret Structure

Trust Anchor Secret (runway/env/<environment>/service/<service-id>/trust_anchor_pem):

{
  "root_ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Intermediate CA Secret (runway/env/<environment>/service/<service-id>/intermediate_cas_pem):

{
  "intermediate_ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

mTLS Headers

When mTLS is enabled, Runway automatically attaches the following headers to requests sent to your backend service:

mtls_headers = [
    "X-Client-Runway-Cc-Present: {client_cert_present}",
    "X-Client-Runway-Cc-Chain-Verified: {client_cert_chain_verified}",
    "X-Client-Runway-Cc-Error: {client_cert_error}",
    "X-Client-Runway-Cc-Sha256-Fingerprint: {client_cert_sha256_fingerprint}",
    "X-Client-Runway-Cc-Serial-Number: {client_cert_serial_number}",
    "X-Client-Runway-Cc-Spiffe-Id: {client_cert_spiffe_id}",
    "X-Client-Runway-Cc-Uri-Sans: {client_cert_uri_sans}",
    "X-Client-Runway-Cc-Dnsname-Sans: {client_cert_dnsname_sans}",
    "X-Client-Runway-Cc-Issuer-Dn: {client_cert_issuer_dn}",
    "X-Client-Runway-Cc-Subject-Dn: {client_cert_subject_dn}",
    "X-Client-Runway-Cc-Leaf: {client_cert_leaf}",
    "X-Client-Runway-Cc-Chain: {client_cert_chain}",
]

These headers provide detailed information about the client certificate validation process. For detailed explanations of each header, refer to Google Cloud’s mTLS custom headers documentation.

Limitations

Unidirectional Authentication: mTLS currently only validates client certificates when connecting to the server. Server-side certificates are not added when your service initiates outbound requests.
Certificate Management: Certificate rotation must be handled manually through Vault updates.