Configuring TLS Context for Flex Gateway in Local Mode

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 YAML configuration file.

You can format the YAML file to configure TLS either for a specific API Instance or or for all API Instances running on your Flex Gateway.

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

Similar to policies, in Local Mode, you apply TLS context via an API instance YAML resource using the Declarative Configuration Reference Guide. For this tutorial you do not need to refer to the reference guide, but you must refer to the TLS inbound and TLS outbound policies to enable mTLS, define TLS direction, and select the API to which to apply TLS:

Flex Gateway implements port-level TLS, meaning if you apply TLS to an API instance that shares a port with other instances, the same TLS context is applied to all instances sharing the port. Flex Gateway supports multiple TLS certificates on a single gateway, but you must apply the certificates to unique ports. If you apply TLS to one API instance, you do not need to apply the same TLS context to instances that share that port. Consequently, you cannot apply different TLS contexts to API instances that share the same port.

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

Configure TLS Context for Flex Gateway as a Linux Service

Configure TLS Context for Flex Gateway in a Docker Container

Configure TLS Context for Flex Gateway in a Kubernetes Cluster

Before You Begin

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

Configure TLS Context for Flex Gateway as a Linux Service

Create a YAML configuration file in the Flex Gateway configuration directory:
```
sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
```

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

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

Transport Layer Security Policy - Outbound

Sample configuration for adding inbound TLS context for a specific API Instance:

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

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.

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

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

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

If you have already added volume for a folder with your Flex Gateway configuration files, go to the last step.

Stop your Flex Gateway and any replicas, using Ctrl+C.
Create a folder in the directory with your Flex Gateway configuration files and name it app.
Restart your Flex Gateway with an additional volume for the new app directory:
```
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```
Specify an optional name you want to assign to your Flex Replica by including the following: -e FLEX_NAME=<name-for-flex-replica> \.

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

Transport Layer Security Policy - Outbound

Sample configuration for adding inbound TLS context for a specific API Instance:

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

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.

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

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

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

Transport Layer Security Policy - Outbound

Sample configuration for adding inbound TLS context for a specific API Instance:

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

Gartner names MuleSoft a Leader

Unleash the power of Salesforce Customer 360 through integration

Anypoint Platform Fundamentals

MuleSoft at World Tour

Gartner names MuleSoft a Leader

Unleash the power of Salesforce Customer 360 through integration

Anypoint Platform Fundamentals

MuleSoft at World Tour

Configuring TLS Context for Flex Gateway in Local Mode

Before You Begin

Configure TLS Context for Flex Gateway as a Linux Service

Configure TLS Context for Flex Gateway in a Docker Container

Configure TLS Context for Flex Gateway in a Kubernetes Cluster

See Also