---
schema_version: "1"
id: a3dbc4c79e356c7eba766a926623748faa98add0b956994814d01d36be546d2c
title: Transport Layer Security Policy - Outbound
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-tls-outbound.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound
source_site: docs.mulesoft.com
content_type: documentation
content_hash: c8d8aab2956ece12474b62e528a5acd72dd34dad97cb2c57d3ad0b96ec93b1a8
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: tls, mtls, transport layer security, outbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Outbound

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

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Outbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables two-way authentication between the API proxy and an upstream service</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni version available</strong></p></td><td><div><div><p>v1.4.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Omni Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config).

## Summary

Omni Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS
(mTLS) in Local Mode.

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni 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 Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

To apply outbound TLS in Local Mode, use the
[Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config) 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 upstream service.

Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API instances
in your Omni Gateway because your API upstream services might come from different providers.
Therefore, no configuration example for outbound TLS on all instances is provided.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

> [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
> Common Name (CN) field is deprecated.
>
> Omni Gateway supports the SAN extension of type `dNSName`.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Configuring Policy Parameters

To enable outbound TLS between an API instance and an upstream service when using Omni 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: //
OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL 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 Omni Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>skipValidation</code> is false</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS for a upstream service.

**Sample configuration for adding outbound TLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: tls-outbound
spec:
  targetRef:
    kind: Service
    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 upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls-outbound
spec:
  targetRef:
    kind: Service
    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_SHA384
```

## TLS Cipher Support on Omni Gateway

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

### Omni Gateway Supported Ciphers

Omni 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 Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

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