Transport Layer Security Policy - Outbound
Policy Name |
Transport Layer Security (TLS) - Outbound |
Summary |
Enables two-way authentication between the API proxy and an upstream service |
Category |
Security |
First Flex version available |
v1.4.0 |
Returned Status Codes |
No return codes exist for this policy. |
|
The following document applies only to Flex Gateway running in Local Mode. To configure TLS in Connected Mode, see Configuring TLS Context for Flex Gateway in Connected Mode. |
Summary
Flex Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS (mTLS) in Local Mode.
To apply outbound TLS in Local Mode, use the Configuring TLS Context for Flex Gateway in Local Mode tutorial and refer to the following configuration files in this documentation.
You can configure an outbound TLS context to enable authentication between an API Instance and an upstream service by binding the TLS policy to the API instance.
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.
Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API Instances in your Flex Gateway because your API upstream services might come from different providers. Therefore, no configuration example for outbound TLS on all instances is provided.
|
TLS policies do not support policy ordering. |
|
Upstream certificates must include the Subject Alternative Name (SAN) extension. The Common Name (CN) field is deprecated. Flex Gateway supports the SAN extension of type |
Configuring Policy Parameters
To enable outbound mTLS when creating an API Instance using Flex Gateway as your runtime, you must manually configure the TLS context in a YAML configuration file.
Refer to the following policy definition and table of parameters:
- policyRef:
name: tls-outbound
config:
skipValidation: <boolean> // REQUIRED
certificate: // REQUIRED
key: <string> // REQUIRED
crt: <string> // REQUIRED
alpn: <array> // OPTIONAL
minversion: <string> // OPTIONAL
maxversion: <string> // OPTIONAL
ciphers: <array> // OPTIONAL
Not including optional parameters in your configuration file applies the parameters default values to your TLS context.
When configuring the ciphers parameter, ensure that your API upstream supports the listed ciphers. For the supported ciphers, see TLS Cipher Support on Flex Gateway.
| Parameter | Required or Optional | Default Value | Description |
|---|---|---|---|
|
Required |
false |
Skipping validation disables outbound mTLS |
|
Optional, unless |
N/A |
The client certificate used in mTLS |
|
Required |
N/A |
A TLS certificate key pair |
|
Required |
N/A |
The private key part of the certificate |
|
Required |
N/A |
The public key part of the certificate |
|
Optional |
|
A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth. |
|
Optional |
|
The minimum TLS version allowed |
|
Optional |
|
The maximum TLS version allowed |
|
Optional |
For the default and other supported ciphers, see TLS Cipher Support on Flex Gateway. |
A list of supported TLS ciphers (IANA format). |
Resource Configuration Examples
Sample configuration for adding outbound TLS context for a specific API Instance:
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
name: tls-outbound
spec:
targetRef:
name: ingress-test-outbound-upstream
policyRef:
name: tls-outbound
config:
skipValidation: true
certificate:
key: |
# -----BEGIN PRIVATE KEY-----
# insert certificate key
# -----END PRIVATE KEY-----
crt: |
# -----BEGIN CERTIFICATE-----
# insert certificate
# -----END CERTIFICATE-----This example uses the default values for alpn, minversion, maxversion, and ciphers.
Sample configuration for adding outbound mTLS context for a specific API Instance::
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
name: mtls-outbound
spec:
targetRef:
name: ingress-test-outbound-upstream
policyRef:
name: tls-outbound
config:
skipValidation: false
trustedCA: |
# -----BEGIN CERTIFICATE-----
# insert certificate
# -----END CERTIFICATE-----
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_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS Cipher Support on Flex Gateway
Flex can support a range of TLS Versions from TLS 1.1 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.
There are no default ciphers for TLS 1.1. To support TLS 1.1, you must list the ciphers to support. If you support TLS 1.1 and TLS 1.2, listing TLS 1.1 ciphers overides the TLS 1.2 defaults. To support both these versions, list all ciphers you want to support.
| 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:
| Cipher | TLS Version | Default | Advice |
|---|---|---|---|
TLS_AES_128_GCM_SHA256 |
1.3 |
Yes |
Secure |
TLS_AES_256_GCM_SHA384 |
1.3 |
Yes |
Secure |
TLS_CHACHA20_POLY1305_SHA256 |
1.3 |
Yes |
Secure |
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 |
1.2 |
Yes |
Recommended |
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 |
1.2 |
Yes |
Recommended |
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 |
1.2 |
Yes |
Recommended |
TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 |
1.2 |
No |
Recommended |
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 |
1.2 |
Yes |
Secure |
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 |
1.2 |
Yes |
Secure |
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 |
1.2 |
Yes |
Secure |
TLS_RSA_WITH_AES_128_GCM_SHA256 |
1.2 |
No |
Weak |
TLS_RSA_WITH_AES_256_GCM_SHA384 |
1.2 |
No |
Weak |
TLS_RSA_WITH_NULL_SHA |
1.1, 1.2 |
No |
Insecure |
TLS_RSA_WITH_AES_128_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_RSA_WITH_AES_256_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_PSK_WITH_AES_128_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_PSK_WITH_AES_256_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA |
1.1, 1.2 |
No |
Weak |
TLS_RSA_WITH_3DES_EDE_CBC_SHA |
1.1 |
No |
Weak |