Contact Us 1-800-596-4880

Configuring TLS Context for Flex Gateway in Connected Mode

Using HTTPS protects the communication between the client and Flex Gateway with encryption. To use HTTPS as your schema when creating an API Instance using Flex Gateway as your runtime, you must configure the TLS context in a YAML configuration file. You can format the YAML file to configure TLS either for a specific API Instance or or for all API Instances running on your Flex Gateway.

Flex Gateway supports regular TLS and inbound mutual authentication TLS (mTLS).

Configuring TLS is the same process for both Local and Connected Mode.

You can configure the TLS context for a Flex Gateway running in a Docker container, as a Linux Service, or as a Kubernetes Ingress controller.

20%

25%

20%

Before You Begin

Before configuring the TLS context for a Flex Gateway, you must complete the following tasks:

Configure TLS Context for Flex Gateway as a Linux Service

  1. Create a YAML configuration file in the Flex Gateway configuration directory:

    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
  2. Update the file with your TLS context configuration details. For example:

    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml

    Sample configuration for adding TLS context for all API Instances running on this Flex Gateway:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: ingress-https-tls
    spec:
      targetRef:
        kind: Selector
        selector:
          kind: ApiInstance
      policyRef:
        name: tls
      config:
        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

    Sample configuration for adding TLS context for a specific 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 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

    Sample configuration for adding an inbound mTLS context for a specific API Instance:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: mtls
    spec:
      targetRef:
        name: ingress-https
      policyRef:
        name: tls
      config:
        requireClientCertificate: true
        trustedCA: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
        certificate:
          key: |
            # -----BEGIN RSA PRIVATE KEY-----
            # insert private key
            # -----END RSA PRIVATE KEY-----
          crt: |
            # -----BEGIN CERTIFICATE-----
            # insert certificate
            # -----END CERTIFICATE-----
  3. Verify that the policy was correctly applied.

    The following example curl command tests an HTTPS endpoint with a certificate that matches the certificate specified in the policy binding configuration resource.

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

    The command should return information on the TLS handshake, as well as an HTTP status of 200 for the endpoint:

    * TLSv1.3 (OUT), TLS handshake, Client hello (1):
    * TLSv1.3 (IN), TLS handshake, Server hello (2):
    * TLSv1.2 (IN), TLS handshake, Certificate (11):
    * TLSv1.2 (IN), TLS handshake, Server key exchange (12):
    * TLSv1.2 (IN), TLS handshake, Server finished (14):
    * TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
    * TLSv1.2 (OUT), TLS change cipher, Client hello (1):
    * TLSv1.2 (OUT), TLS handshake, Finished (20):
    * SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305
    * ALPN, server did not agree to a protocol
    ...
    > HTTP/1.1 200 OK

    For inbound mTLS, the following example curl command requests an API proxy whose basepath is /.

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

    The configuration key and crt values must be correctly indented, otherwise curl returns the following error when attempting to test the endpoint:

    curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number

    See Transport Layer Security Policy for more information about TLS context configuration options.

Configure TLS Context for Flex Gateway in a Docker Container

If you have already added volume for a folder with your Flex Gateway configuration files, go to the last step.
  1. Stop your Flex Gateway and any replicas, using Ctrl+C.

  2. Create a folder in the directory with your Flex Gateway configuration files and name it app.

  3. Restart your Flex Gateway with an additional volume for the new app directory:

    docker run --rm \
    -v <absolute-path-to-directory-with-gateway-files>/:/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    Specify an optional name you want to assign to your Flex Replica by including the following: -e FLEX_NAME=<name-for-flex-replica> \.

    Sample configuration for adding TLS context for all API Instances running on this Flex Gateway:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: ingress-https-tls
    spec:
      targetRef:
        kind: Selector
        selector:
          kind: ApiInstance
      policyRef:
        name: tls
      config:
        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

    Sample configuration for adding TLS context for a specific 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 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

    Sample configuration for adding an inbound mTLS context for a specific API Instance:

    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: mtls
    spec:
      targetRef:
        name: ingress-https
      policyRef:
        name: tls
      config:
        requireClientCertificate: true
        trustedCA: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
        certificate:
          key: |
            # -----BEGIN RSA PRIVATE KEY-----
            # insert private key
            # -----END RSA PRIVATE KEY-----
          crt: |
            # -----BEGIN CERTIFICATE-----
            # insert certificate
            # -----END CERTIFICATE-----
  4. Verify that the policy was correctly applied.

    The following example curl command tests an HTTPS endpoint with a certificate that matches the certificate specified in the policy binding configuration resource.

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

    The command should return information on the TLS handshake, as well as an HTTP status of 200 for the endpoint:

    * TLSv1.3 (OUT), TLS handshake, Client hello (1):
    * TLSv1.3 (IN), TLS handshake, Server hello (2):
    * TLSv1.2 (IN), TLS handshake, Certificate (11):
    * TLSv1.2 (IN), TLS handshake, Server key exchange (12):
    * TLSv1.2 (IN), TLS handshake, Server finished (14):
    * TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
    * TLSv1.2 (OUT), TLS change cipher, Client hello (1):
    * TLSv1.2 (OUT), TLS handshake, Finished (20):
    * SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305
    * ALPN, server did not agree to a protocol
    ...
    > HTTP/1.1 200 OK

    For inbound mTLS, the following example curl command requests an API proxy whose basepath is /.

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

    The configuration key and crt values must be correctly indented, otherwise curl returns the following error when attempting to test the endpoint:

    curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number

    See Transport Layer Security Policy for more information about TLS context configuration options.

Configure TLS Context for Flex Gateway as a Kubernetes Ingress Controller

To configure the TLS context for Flex Gateway, create a new resource using a YAML configuration file with your TLS context details.

Sample configuration for adding TLS context for all API Instances running on this Flex Gateway:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: Selector
    selector:
      kind: ApiInstance
  policyRef:
    name: tls
  config:
    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

Sample configuration for adding TLS context for a specific 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 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

Sample configuration for adding an inbound mTLS context for a specific API Instance:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls
spec:
  targetRef:
    name: ingress-https
  policyRef:
    name: tls
  config:
    requireClientCertificate: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN RSA PRIVATE KEY-----
        # insert private key
        # -----END RSA PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----

See Transport Layer Security Policy for more information about TLS context configuration options.