Contact Us 1-800-596-4880

Configuring TLS Context for Omni Gateway in Connected 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 Connected Mode via:

  • API Manager: Applies a TLS context to one API instance or upstream service. Requires a secret group.

  • Runtime Manager runtime configurations: Applies default TLS contexts to all API instances and upstream services in the gateway. Requires a secret group.

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

Runtime Manager Runtime Configuration and Configuration Resource Priority

To make the Configuration resource value take precedence, add the flex.mulesoft.com/resource-priority label to the Configuration resource with a value of 2 or higher:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <configuration-name>
  labels:
    flex.mulesoft.com/resource-priority: "2"
spec:
  # configuration values

Omni Gateway assigns these priorities:

  • Runtime Manager runtime configuration: 1

  • Configuration resource without the label, or with a label value that isn’t an integer: 0

  • Configuration resource with the label: the label value

A Configuration resource with a priority of 2 or higher overrides the Runtime Manager runtime configuration values. If you set the Configuration priority to 1, the Runtime Manager runtime configuration values take precedence.

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.

Create a TLS Context in Secrets Manager

To apply a TLS context in API Manager or Runtime Manager, you must first create the TLS context in a downloadable secret group in Secrets Manager. API Manager and Runtime Manager list only the TLS contexts in your secret groups.

Before you create a TLS context, create a secret group and add a keystore, a truststore, or both, depending on the TLS context you need:

Setting Inbound TLS Inbound mTLS Outbound TLS Outbound mTLS

Keystore

Required

Required

Not used

Required

Truststore

Not used

Required

Required, unless Skip server certificate validation is selected

Required

Validate Client certificate

Not selected

Selected

Not used

Not used

Skip server certificate validation

Not used

Not used

Either

Not selected

You can use one TLS context for both directions if it includes the settings for both. You can’t use one TLS context for both TLS and mTLS in the same direction.

To create a TLS context:

  1. In Anypoint Platform, select Secrets Manager.

  2. Make your secret group downloadable:

    1. Click the pencil icon next to the name of your secret group.

    2. Select Secret Group Downloadable, and then click Save.

  3. Click Edit for the secret group.

  4. Select TLS Context, and then click Add TLS Context.

  5. Enter the TLS context settings:

    • Name: A name for the TLS context.

    • Target: Select Omni Gateway.

    • Min TLS Version and Max TLS Version: The range of TLS versions to support. To support one version, select the same version for both.

    • Keystore: The certificate that Omni Gateway presents to the remote party.

    • Truststore: The CAs that Omni Gateway uses to validate the remote party’s certificate.

    • Expiration Date: Optional. An expiration date for the TLS context.

    • ALPN Protocols: The application-level protocols to support. The default is H2 - HTTP/1.1.

    • Inbound Settings: To require client certificates (inbound mTLS), select Validate Client certificate.

    • Outbound Settings: To accept the upstream server certificate without validating it, select Skip server certificate validation.

  6. Optional: To add TLS 1.2 ciphers to the defaults, click Ciphers and select the ciphers. For the supported ciphers, see Supported TLS Versions and Ciphers.

    Cipher selection isn’t available if you support only TLS 1.3.

  7. Click Save.

Apply a TLS Context to an API Instance

Before you apply a TLS context, create a TLS context in a downloadable secret group. You can’t apply a TLS context in API Manager without a secret group.

Apply a TLS context when you create an API instance or edit an existing one. For more information, see Adding an Omni Gateway API Instance and Editing an API Instance.

  1. In Anypoint Platform, select API Manager.

  2. Create an API instance, or open the Settings of an existing API instance.

  3. To apply an inbound TLS context, in the downstream configuration, select HTTPS for Protocol, click Add TLS Context, select a Secret Group and a TLS Context, and click Ok.

  4. To apply an outbound TLS context, in the upstream configuration, click Add TLS Context, select a Secret Group and a TLS Context, and click Ok.

  5. Save the API instance.

Inbound TLS Contexts on Shared Ports

When you apply, edit, or remove the inbound TLS context of an API instance that shares its port, API Manager lists the other API instances on the port. To apply the same inbound TLS context to them, override their inbound TLS context. Overriding redeploys the API instances, which causes a brief downtime.

If you change the port of an API instance, the inbound TLS context remains applied to the API instances on the previous port.

Update a TLS Context

If you edit a secret group or TLS context that’s applied to an API instance, redeploy each affected API instance to apply the changes:

  1. In Anypoint Platform, select API Manager.

  2. Click the name of the API instance.

  3. Click Runtime & Endpoint Configuration > Save & Apply.

For how to edit a secret group, see Edit a Secret Group.

Configure Default TLS Contexts in Runtime Manager

Before you configure a default TLS context, create a TLS context in a downloadable secret group. You can’t configure a default TLS context in Runtime Manager without a secret group. A default inbound TLS context requires a keystore.

  1. In Anypoint Platform, select Runtime Manager.

  2. Select Omni Gateways.

  3. Select your Omni Gateway.

  4. Open Runtime Configurations.

  5. Open TLS.

  6. To configure a default inbound TLS context, in Default Inbound TLS, select a Secret Group and a TLS Context.

  7. To configure a default outbound TLS context, in Default Outbound TLS, select a Secret Group and a TLS Context.

  8. Click Apply changes.

To remove a default TLS context, clear its Secret Group and TLS Context fields, and then click Apply changes.

If Omni Gateway can’t use the selected TLS context, for example, because the TLS context was deleted, Omni Gateway ignores that default TLS context, logs a warning, and applies the rest of the runtime configuration.

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.

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