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 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
The following tutorials demonstrate how to apply a configured PolicyBinding
resource. For how to configure the resource, see the policy configuration pages:
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.
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 - 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
To comply with security standards, all certificates must be 2048 bits or longer.
-
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
andcrt
values must be correctly indented, otherwisecurl
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, skip to the last step. |
-
Press Ctrl+C to stop your Flex Gateway and any replicas.
-
Create a folder named
app
in the directory with your Flex Gateway configuration files. -
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 - 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
To comply with security standards, all certificates must be 2048 bits or longer.
-
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
andcrt
values must be correctly indented, otherwisecurl
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 - 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
To comply with security standards, all certificates must be 2048 bits or longer.