Contact Us 1-800-596-4880

Configuring TLS Context for Omni Gateway in Local Mode

Transport Layer Security (TLS) encrypts communication between clients, Omni Gateway, and upstream services. Omni Gateway supports:

  • Inbound TLS
    TLS between a client and an API instance (HTTPS).

  • Outbound TLS
    TLS between Omni Gateway and an upstream service, and between Omni Gateway and the services that policies call.

  • Inbound mutual authentication TLS (mTLS)
    Inbound TLS where the client also presents a certificate that Omni Gateway validates.

  • Outbound mutual authentication TLS (mTLS)
    Outbound TLS where Omni Gateway also presents a certificate that the upstream service validates.

You can apply TLS contexts individually or configure default TLS contexts:

  • Inbound TLS context
    Apply to an API instance. Because inbound TLS applies at the port level, the TLS context also applies to every API instance that shares the port. A default inbound TLS context applies to every HTTPS API instance that doesn’t have its own inbound TLS context.

  • Outbound TLS context
    Apply to an upstream service. Each upstream service can have its own TLS context. A default outbound TLS context applies to every HTTPS upstream service that doesn’t have its own outbound TLS context. It also applies to outgoing policy requests, such as requests that the Basic Authentication - LDAP policy makes to an LDAP server.

You can configure TLS in Local Mode via:

  • Policy binding: Applies a TLS context to one API instance or upstream service.

  • Configuration YAML resource: Applies default TLS contexts to all API instances and upstream services in the gateway.

Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set, in this order of precedence:

  1. TLS context applied to the API instance or upstream service: A TLS context applied in API Manager, or with the Transport Layer Security Policy - Inbound (tls) or Transport Layer Security Policy - Outbound (tls-outbound). This TLS context overrides the default TLS context.

  2. Default TLS context: Used if the API instance or upstream service doesn’t have its own TLS context.

  3. Built-in outbound TLS: Used for upstream services and outgoing policy requests if no other TLS context applies. Omni Gateway validates the server certificate against the operating system CAs, uses the default ciphers, and doesn’t present a client certificate.

Default TLS contexts apply only to API instances and upstream services whose URL uses https://. API instances and upstream services that use http:// aren’t affected.

Certificate Requirements

  • Certificates must be 2048 bits or longer.

  • Certificates, keys, and CAs must be in Privacy Enhanced Mail (PEM) format.

  • Upstream server certificates must include the Subject Alternative Name (SAN) extension of type dNSName. The Common Name (CN) field is deprecated.

  • Omni Gateway doesn’t support the Authority Information Access (AIA) certificate extension for outbound TLS.

Apply a TLS Context with a Policy Binding

To apply a TLS context to an API instance or upstream service, create a PolicyBinding resource:

  • For inbound TLS, bind the tls policy to an API instance. To apply it to all API instances, use a Selector target.

  • For outbound TLS, bind the tls-outbound policy to an upstream service.

This example applies inbound TLS to an 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 private key
        -----END PRIVATE KEY-----
      crt: |
        -----BEGIN CERTIFICATE-----
        # insert certificate
        -----END CERTIFICATE-----

This example applies outbound TLS to an upstream service:

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: false
    trustedCA: |
      -----BEGIN CERTIFICATE-----
      # insert the CA that signs the upstream server certificate
      -----END CERTIFICATE-----

For all parameters and mTLS examples, see Transport Layer Security Policy - Inbound and Transport Layer Security Policy - Outbound. TLS policies don’t support policy ordering.

Configure Default TLS Contexts with a Configuration Resource

Configure default TLS contexts in a Configuration resource. Both inbound and outbound are optional:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: default-tls
spec:
  defaultTLS:
    inbound:
      certificate:
        key: <string>
        crt: <string>
        keyPassphrase: <string>
      requireClientCertificate: <boolean>
      trustedCA: <string>
      alpn: <array>
      minVersion: <string>
      maxVersion: <string>
      ciphers: <array>
    outbound:
      skipValidation: <boolean>
      trustedCA: <string>
      certificate:
        key: <string>
        crt: <string>
        keyPassphrase: <string>
      alpn: <array>
      minVersion: <string>
      maxVersion: <string>
      ciphers: <array>

Omni Gateway validates each default TLS context when you apply the resource. If a default TLS context is invalid, for example, because the certificate and key don’t match or a cipher isn’t supported, Omni Gateway rejects the resource and logs an error.

Parameters for inbound and outbound:

Parameter Required or Optional Default Value Description

certificate.crt and certificate.key

Required for inbound. Optional for outbound.

N/A

The certificate and private key that Omni Gateway presents. For outbound, the certificate enables mTLS.

certificate.keyPassphrase

Optional, unless the private key is encrypted

N/A

The passphrase that decrypts the private key.

trustedCA

Optional

inbound: N/A
outbound: The operating system CAs

For inbound, the CA that validates client certificates. Required if requireClientCertificate is true.
For outbound, the CA that validates upstream server certificates.

requireClientCertificate

Optional. inbound only.

false

If true, clients must present a certificate signed by trustedCA (inbound mTLS).

skipValidation

Optional. outbound only.

false

If true, Omni Gateway doesn’t validate upstream server certificates and logs a warning.

alpn

Optional

http/1.1 and h2

A prioritized list of application-level protocols. Supported values are http/1.1 and h2.

minVersion and maxVersion

Optional

1.2 and 1.3

The minimum and maximum TLS versions. Supported values are 1.2 and 1.3.

ciphers

Optional

The default TLS 1.2 ciphers in Supported TLS Versions and Ciphers. outbound excludes TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256.

A list of TLS 1.2 ciphers, in IANA format.

In the Configuration resource, the TLS version parameters are minVersion and maxVersion. In the tls and tls-outbound policies, the same parameters are lowercase: minversion and maxversion.

This example configures a default inbound TLS context and a default outbound TLS context that trusts a private CA:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: default-tls
spec:
  defaultTLS:
    inbound:
      certificate:
        key: |
          -----BEGIN PRIVATE KEY-----
          # insert private key
          -----END PRIVATE KEY-----
        crt: |
          -----BEGIN CERTIFICATE-----
          # insert certificate
          -----END CERTIFICATE-----
    outbound:
      trustedCA: |
        -----BEGIN CERTIFICATE-----
        # insert the CA that signs the upstream server certificates
        -----END CERTIFICATE-----
The defaultTLS.outboundPolicyCalls parameter is deprecated. Use defaultTLS.outbound instead. For details, see Configuring TLS for Outgoing Policy Requests.

Add the Configuration Files to Omni Gateway

Add the YAML file to Omni Gateway:

  • Linux service: Save the YAML file in /usr/local/share/mulesoft/flex-gateway/conf.d/.

  • Docker container: Save the YAML file in the directory that you mount to /usr/local/share/mulesoft/flex-gateway/conf.d in the container, for example, with -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d.

  • Kubernetes cluster: Apply the YAML file with kubectl apply -f <file-name>.yaml.

Verify Inbound TLS

Send a request to an HTTPS API instance:

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

The output shows the TLS handshake and an HTTP 200 response. For inbound mTLS, also pass the client certificate and key:

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

If curl returns error:1408F10B:SSL routines:ssl3_get_record:wrong version number, check the indentation of the key and crt values in your YAML file.

Supported TLS Versions and Ciphers

Omni Gateway supports TLS 1.2 and TLS 1.3:

  • TLS 1.3: Omni Gateway always supports all TLS 1.3 ciphers. You can’t customize them.

  • TLS 1.2: Omni Gateway supports the default ciphers unless you customize them. In Secrets Manager, you add ciphers to the defaults. In a configuration file, the ciphers list replaces the defaults, so include every cipher that you want to support.

For outbound TLS, ensure that your upstream services support the TLS versions and ciphers that you configure.

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_AES_128_CBC_SHA

1.2

No

Weak

TLS_RSA_WITH_AES_256_CBC_SHA

1.2

No

Weak

TLS_PSK_WITH_AES_128_CBC_SHA

1.2

No

Weak

TLS_PSK_WITH_AES_256_CBC_SHA

1.2

No

Weak

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

1.2

No

Weak

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

1.2

No

Weak

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

1.2

No

Weak

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

1.2

No

Weak

TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA

1.2

No

Weak

TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA

1.2

No

Weak