---
schema_version: "1"
id: 1cb72f7a2cb582b77e2552b3596f68942cbae56cc1baf3d07795034631494211
title: Configuring TLS Context for Flex Gateway in Local Mode
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.12/flex-local-tls-config.md
canonical_url: https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config
source_site: docs.mulesoft.com
content_type: documentation
content_hash: c1201944d5b3674e424b126bca944765c80b239b4b2f9a3c206fa792431eff31
description: MuleSoft Documentation Site
release: "1.12"
latest: false
---
---
product: Omni Gateway
version: 1.12
---

# Configuring TLS Context for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. To use TLS when creating an API instance using Flex Gateway in
Local Mode as your runtime, you must configure the TLS context in a `PolicyBinding` YAML
configuration file.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Flex Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

The following tutorials demonstrate how to apply a configured `PolicyBinding` resource. For how to
configure the resource, see the policy configuration pages:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

For inbound TLS, you bind the policy resource to the API instance. For outbound TLS, you bind the
policy resource to the upstream service.

You can configure the TLS context for a Flex Gateway running in a Docker container, as a Linux
Service, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure TLS Context for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure TLS Context for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure TLS Context for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring the TLS context for a Flex Gateway, you must complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

## Configure TLS Context for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

2.  Update the file with your TLS context configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

3.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Flex Gateway in a Docker Container

> [!NOTE] If you have already added volume for a folder with your Flex Gateway configuration files,
> skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your TLS context details.

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

5.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Flex Gateway in a Kubernetes Cluster

To configure the TLS context for Flex Gateway, create a new resource using a YAML configuration file
with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration
file options, such as mTLS and outbound TLS, see:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

  **Sample configuration for adding inbound TLS context for a specific API instance:**

  ```yaml
  apiVersion: gateway.mulesoft.com/v1alpha1
  kind: PolicyBinding
  metadata:
    name: ingress-https-tls
  spec:
    targetRef:
      kind: ApiInstance
      name: ingress-https
    policyRef:
      name: tls
    config:
      certificate:
        key: |
          # -----BEGIN PRIVATE KEY-----
          # insert certificate key
          # -----END PRIVATE KEY-----
        crt: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
      alpn:
        - http/1.1
        - h2
      minversion: "1.1"
      maxversion: "1.3"
      ciphers:
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        - TLS_RSA_WITH_AES_128_GCM_SHA256
        - TLS_RSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        - TLS_RSA_WITH_AES_256_GCM_SHA384
        - TLS_RSA_WITH_AES_256_CBC_SHA
  ```

  > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)