Contact Us 1-800-596-4880

Configuring TLS Context for Managed Omni Gateway

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 for Managed Omni Gateway via:

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

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

  • CloudHub 2.0 private spaces: Manages inbound TLS for Managed Omni Gateway on CloudHub 2.0.

  • Policy bindings on Runtime Fabric: Configures inbound TLS behind an OpenShift route and trusts upstream services signed by a private CA.

Outbound TLS contexts are the same for Managed Omni Gateway and Self-Managed Omni Gateway in Connected Mode. You can use the same TLS contexts for both.

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.

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.

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.

For Managed Omni Gateway on Runtime Fabric with last-mile security, the default inbound TLS context replaces the self-signed certificate that Omni Gateway presents to the cluster ingress. Ensure that the destinationCACertificate of your route template signs the certificate in the default inbound TLS context. See Configure Inbound TLS on Runtime Fabric on OpenShift.

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 outbound TLS context, in the upstream configuration, click Add TLS Context, select a Secret Group and a TLS Context, and click Ok.

  4. Save the API instance.

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 Inbound TLS on CloudHub 2.0

For Managed Omni Gateway deployed on CloudHub 2.0, the CloudHub 2.0 space manages the inbound TLS.

To configure a TLS context for the private space you’re deploying your Managed Omni Gateway to, see Configuring Domains and Certificates (TLS Context) for a Private Space. You can’t edit the TLS context for a shared space.

Configuring a TLS context for your private space means all APIs deployed to Managed Omni Gateways in the private space are HTTPS and secure.

Configure Inbound TLS on Runtime Fabric on OpenShift

For Managed Omni Gateway deployed on Runtime Fabric on OpenShift, terminate external TLS at an OpenShift route and re-encrypt traffic to the gateway. This configuration uses two TLS connections:

  1. The external client connects to the OpenShift route, which presents the cluster wildcard certificate.

  2. The OpenShift route connects to Managed Omni Gateway, which presents its internal certificate. The route validates this certificate by using the destination CA certificate.

You must configure both of these resources together:

  • An HTTPRouteTemplate resource with reencrypt TLS termination, which configures the OpenShift route.

  • A PolicyBinding resource for the tls inbound policy, which configures HTTPS on the APIs.

If you configure only the route template, the route can’t connect to the APIs over HTTPS. If you configure only the policy binding, external clients don’t connect to the gateway through the route with the cluster wildcard certificate.

Instead of a PolicyBinding resource for each API, you can configure a default inbound TLS context that applies to every HTTPS API that doesn’t have an inbound TLS context. See Configure Default TLS Contexts in Runtime Manager.

Don’t create the OpenShift Route resource directly. Instead, create an HTTPRouteTemplate resource. The Runtime Fabric agent renders the template into the Route resource and keeps it reconciled.

Before You Begin

Before configuring inbound TLS for Managed Omni Gateway on Runtime Fabric, make sure that you have:

  • A Managed Omni Gateway deployed to Runtime Fabric. See Deploy a Managed Omni Gateway.

  • The cluster wildcard certificate and private key, in PEM format.

  • The CA certificate that signs the internal certificate of Managed Omni Gateway, in PEM format.

Create the Route Template

  1. Create a YAML file with an HTTPRouteTemplate resource:

    apiVersion: rtf.mulesoft.com/v1
    kind: HTTPRouteTemplate
    metadata:
      name: omni-ingress-reencrypt
      namespace: rtf
    spec:
      baseEndpoints:
        - https://<public-hostname>/
      resources: |
        apiVersion: route.openshift.io/v1
        kind: Route
        metadata:
          name: {{ .ResourceName }}
          namespace: {{ .Namespace }}
        spec:
          host: {{ .Host }}
          path: {{ .Path }}
          to:
            kind: Service
            name: {{ .Service.Name }}
      tls:
        termination: reencrypt
        key: <cluster-wildcard-key-PEM>
        certificate: <cluster-wildcard-cert-PEM>
        caCertificate: <issuing-CA-chain-PEM>
        destinationCACertificate: <omni-gateway-CA-PEM>

    Set the tls parameters as described in TLS Parameters.

  2. Apply the resource:

    oc apply -f <file-name>.yaml

Configure HTTPS on the APIs

The reencrypt route connects to the gateway over HTTPS, so the APIs on Managed Omni Gateway must also serve HTTPS. To configure HTTPS on the APIs, bind the tls inbound policy to them. You must apply this binding in addition to the HTTPRouteTemplate resource that you create in Create the Route Template.

  1. Create a YAML file with a PolicyBinding resource.

    Inbound TLS applies to the port of each API instance that the binding selects, and to all other API instances that share that port. Select the API instances based on the traffic that the gateway serves.

    If the gateway serves only inbound traffic, apply HTTPS to all APIs on the gateway by using a Selector target with no labels:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: tls-inbound-all-apis
      namespace: <omni-gateway-namespace>
      labels:
        rtf.mulesoft.com/target-id: <omni-gateway-id>
    spec:
      targetRef:
        kind: Selector
        selector:
          kind: ApiInstance
      policyRef:
        name: tls
      config:
        # TLS inbound parameters

    If the gateway serves as both the ingress and the egress gateway, select one API instance on the inbound port 8081, by its ID. Because inbound TLS applies to the port, all API instances on 8081 serve HTTPS, and the egress port 8082 continues to serve HTTP:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: tls-inbound-ingress-port
      namespace: <omni-gateway-namespace>
      labels:
        rtf.mulesoft.com/target-id: <omni-gateway-id>
    spec:
      targetRef:
        kind: Selector
        selector:
          kind: ApiInstance
          labels:
            flex.mulesoft.com/apiinstance-id: "<api-instance-id>"
      policyRef:
        name: tls
      config:
        # TLS inbound parameters

    Replace <api-instance-id> with the ID of an API instance on the inbound port. Find the ID in API Manager.

    If you delete or re-create this API instance, the binding no longer selects any API instance, and the inbound port serves HTTP. After you re-create the API instance, update the ID in the binding. To avoid this dependency, deploy separate ingress and egress gateways. See Deploying Agent Network Ingress and Egress Managed Omni Gateways.

    In both examples, replace <omni-gateway-namespace> with the namespace of the Managed Omni Gateway and <omni-gateway-id> with the gateway ID from Runtime Manager.

    For the parameters that you can set in config, see Transport Layer Security Policy - Inbound.

  2. Apply the resource:

    oc apply -f <file-name>.yaml

Verify the Inbound TLS Configuration

After you apply both resources, run the following command from outside the cluster:

curl -v https://<public-hostname>

The TLS handshake completes and the response presents the cluster wildcard certificate, not the internal *.svc.cluster.local certificate of the gateway.

TLS Parameters

In the HTTPRouteTemplate resource that you create in Create the Route Template, set tls using these parameters:

Parameter Required or Optional Description

termination

Required

Set to reencrypt.

key

Required

Private key of the cluster wildcard certificate.

certificate

Required

Cluster wildcard certificate that the route presents to external clients.

caCertificate

Optional

CA chain that issued the cluster wildcard certificate.

destinationCACertificate

Required

CA certificate that signs the internal certificate of Managed Omni Gateway. The route uses this CA to validate the gateway.

Trust Upstreams Signed by a Private CA on Runtime Fabric

For Managed Omni Gateway on Runtime Fabric, you can trust upstream services whose server certificates are signed by a private or corporate CA, such as a large language model (LLM) endpoint that uses private PKI.

Managed Omni Gateway doesn’t inherit the cluster CA bundle, such as the trustedCA bundle from the OpenShift cluster Proxy resource. Provide the CA to the gateway in a tls-outbound policy binding.

When you configure trustedCA, the CA replaces the default CA bundle for the upstreams that the binding matches. Include the complete CA chain for every matched upstream.

trustedCA accepts only an inline PEM value. You can’t reference a Kubernetes secret or config map.

  1. Create a YAML file with a PolicyBinding resource.

    To apply the CA to all upstream services, use a Selector target with no labels:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: tls-outbound-all-upstreams
      namespace: <omni-gateway-namespace>
      labels:
        rtf.mulesoft.com/target-id: <omni-gateway-id>
    spec:
      targetRef:
        kind: Selector
        selector:
          kind: Service
      policyRef:
        name: tls-outbound
      config:
        skipValidation: false
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          # insert the complete CA bundle for all upstreams
          -----END CERTIFICATE-----

    To apply the CA to a single upstream service, set targetRef to the service instead:

      targetRef:
        kind: Service
        name: <upstream-service-name>

    Replace <omni-gateway-namespace> with the namespace of the Managed Omni Gateway and <omni-gateway-id> with the gateway ID from Runtime Manager.

    If the upstream also requires a client certificate, add config.certificate. For all parameters, see Transport Layer Security Policy - Outbound.

  2. Apply the resource:

    • Kubernetes

    • OpenShift

    kubectl apply -f <file-name>.yaml
    oc apply -f <file-name>.yaml
  3. Verify that the egress gateway connects to the upstream without a certificate validation error:

    • Kubernetes

    • OpenShift

    kubectl get pods -n <omni-gateway-namespace>
    kubectl exec -n <omni-gateway-namespace> <omni-egress-pod> -c app -- flexctl check http https://<upstream-host>
    oc get pods -n <omni-gateway-namespace>
    oc exec -n <omni-gateway-namespace> <omni-egress-pod> -c app -- flexctl check http https://<upstream-host>

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