> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# TLS configuration

> Configure TLS termination, cipher suites, backend TLS, and mutual TLS for agentgateway listeners.

Agentgateway supports HTTPS listeners with full TLS termination, configurable cipher suites, TLS version pinning, backend TLS for upstream connections, and mutual TLS (mTLS) for client certificate authentication.

## Basic TLS termination

To expose a listener over HTTPS, set the listener `protocol` to `HTTPS` and supply a `tls` block with the paths to your certificate and private key.

```yaml theme={null}
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTPS
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem
    routes:
    - backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]
```

<Note>
  This is the exact configuration from `examples/tls/config.yaml`. Self-signed certificates require the `-k` flag when testing with `curl`.
</Note>

Verify that TLS is working:

```bash theme={null}
curl https://localhost:3000 -k
# Not Acceptable: Client must accept text/event-stream
```

The request fails because no valid MCP request was sent, but the TLS handshake succeeded.

<Warning>
  The MCP Inspector does not support unverified (self-signed) TLS certificates. Use `curl -k` or a CA-signed certificate when testing.
</Warning>

## TLS fields reference

| Field               | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `tls.cert`          | Path to the PEM-encoded certificate file                         |
| `tls.key`           | Path to the PEM-encoded private key file                         |
| `tls.root`          | Optional path to a CA certificate for client verification (mTLS) |
| `tls.cipherSuites`  | Optional cipher suite allowlist — order is preserved             |
| `tls.minTLSVersion` | Minimum TLS version. Only `1.2` and `1.3` are supported          |
| `tls.maxTLSVersion` | Maximum TLS version. Only `1.2` and `1.3` are supported          |

## Cipher suites

You can restrict which cipher suites the listener negotiates. The order you specify is preserved — agentgateway will prefer suites listed first.

<Tabs>
  <Tab title="TLS 1.3 only">
    ```yaml theme={null}
    tls:
      cert: certs/cert.pem
      key: certs/key.pem
      minTLSVersion: "1.3"
      cipherSuites:
        - TLS13_AES_256_GCM_SHA384
        - TLS13_AES_128_GCM_SHA256
        - TLS13_CHACHA20_POLY1305_SHA256
    ```
  </Tab>

  <Tab title="TLS 1.2 + 1.3">
    ```yaml theme={null}
    tls:
      cert: certs/cert.pem
      key: certs/key.pem
      minTLSVersion: "1.2"
      maxTLSVersion: "1.3"
      cipherSuites:
        - TLS13_AES_256_GCM_SHA384
        - TLS13_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    ```
  </Tab>
</Tabs>

### Supported cipher suites

<AccordionGroup>
  <Accordion title="TLS 1.3 cipher suites">
    | Cipher suite                     |
    | -------------------------------- |
    | `TLS13_AES_256_GCM_SHA384`       |
    | `TLS13_AES_128_GCM_SHA256`       |
    | `TLS13_CHACHA20_POLY1305_SHA256` |
  </Accordion>

  <Accordion title="TLS 1.2 cipher suites">
    | Cipher suite                                    |
    | ----------------------------------------------- |
    | `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`   |
  </Accordion>
</AccordionGroup>

## TLS version control

Agentgateway supports TLS 1.2 and TLS 1.3 only. Use `minTLSVersion` and `maxTLSVersion` to pin the acceptable range.

```yaml theme={null}
tls:
  cert: certs/cert.pem
  key: certs/key.pem
  minTLSVersion: "1.2"
  maxTLSVersion: "1.3"
```

<Note>
  Attempts to configure versions below TLS 1.2 are not supported.
</Note>

## Backend TLS

When agentgateway proxies traffic to an upstream service that requires TLS, configure `backendTLS` on the route policy. Agentgateway will use the system trusted CA certificates by default, and automatically derive the SNI from the destination hostname.

```yaml theme={null}
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: secure-upstream
            http:
              host: api.example.com
              port: 443
      policies:
        backendTLS:
          tls: {}
```

### Custom CA certificate

To verify the upstream with a custom CA, reference a ConfigMap containing the CA certificate:

```yaml theme={null}
policies:
  backendTLS:
    tls:
      caCertificateRefs:
        - name: my-ca-configmap
```

### Custom SNI

Override the SNI sent during the TLS handshake:

```yaml theme={null}
policies:
  backendTLS:
    tls:
      sni: api.internal.example.com
```

### Skip verification (insecure)

<Warning>
  Skipping TLS verification is insecure. Only use this in development environments.
</Warning>

```yaml theme={null}
policies:
  backendTLS:
    tls:
      insecureSkipVerify: All
```

The `Hostname` mode verifies the CA certificate but ignores hostname/SAN mismatches.

## Mutual TLS (mTLS)

mTLS requires clients to present a certificate signed by a trusted CA. Set the `tls.root` field to the CA certificate path on the listener.

```yaml theme={null}
binds:
- port: 3000
  listeners:
  - name: mtls-listener
    protocol: HTTPS
    tls:
      cert: certs/server-cert.pem
      key: certs/server-key.pem
      root: certs/ca-cert.pem
    routes:
    - backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]
```

### Backend mTLS

To use a client certificate when connecting to a backend (outbound mTLS), reference a Kubernetes Secret containing the client certificate:

```yaml theme={null}
policies:
  backendTLS:
    tls:
      mtlsCertificateRef:
        - name: client-tls-secret
```

The Secret must be of type `kubernetes.io/tls` with `tls.crt` and `tls.key` data fields. An optional `ca.crt` field, if present, will be used to verify the server certificate.

## Complete example

<Steps>
  <Step title="Generate a self-signed certificate">
    ```bash theme={null}
    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
      -days 365 -nodes -subj '/CN=localhost'
    ```
  </Step>

  <Step title="Write the agentgateway config">
    ```yaml theme={null}
    # yaml-language-server: $schema=https://agentgateway.dev/schema/config
    binds:
    - port: 3000
      listeners:
      - name: default
        protocol: HTTPS
        tls:
          cert: cert.pem
          key: key.pem
          minTLSVersion: "1.2"
          cipherSuites:
            - TLS13_AES_256_GCM_SHA384
            - TLS13_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        routes:
        - backends:
          - mcp:
              targets:
              - name: everything
                stdio:
                  cmd: npx
                  args: ["@modelcontextprotocol/server-everything"]
    ```
  </Step>

  <Step title="Start agentgateway">
    ```bash theme={null}
    cargo run -- -f config.yaml
    ```
  </Step>

  <Step title="Test the connection">
    ```bash theme={null}
    curl https://localhost:3000 -k
    # Not Acceptable: Client must accept text/event-stream
    ```
  </Step>
</Steps>