Using mTLS with the Strivacity Login Gateway

Mutual Transport Layer Security (mTLS) can be used to secure communications between the Strivacity Login Gateway and upstream (proxied) services.

When the Login Gateway operates in proxy mode—where the gateway is responsible not only for the authentication interactions but also for directing traffic to protected systems—it may need to establish a secure connection with these upstream services. This prevents unauthorized access due to network topology, deployment choices, or other security concerns.

In the diagram above, mTLS secures flow 3—the communication between the gateway and the upstream service. The Login Gateway already communicates using HTTPS with the Strivacity cloud (flow 2). Public-facing traffic (flow 1) can be secured using standard SSL/TLS configuration, but this is independent of mTLS.

Mutual TLS in this case requires configuring both sides of the communication.

Configuring mTLS for protected services

For mutual TLS authentication, both the Login Gateway and the upstream service must be configured to verify each other's identity using certificates issued by a Certificate Authority (CA).

• Required configuration for the gateway:
  • A certificate and key generated from a CA. None of these need to be public; a private self-signed CA can be used to generate the certificate. These will be referred to as the gateway certificate, gateway key, and gateway CA.
• Required configuration for the upstream services:
  • Services must be configured with certificates and keys. All certificates should be generated from the same CA, which can be a private or self-signed CA. This will be referred to as the upstream CA.
• These CA certificates do not need to be distinct; a single CA can be used for both purposes if desired. However, this is not required.

In general, each side is configured with a certificate and key, along with the CA from the other end of the connection. The gateway is configured with the gateway certificate, key, and the upstream CA, while the upstream service is configured with its own certificate, key, and the gateway CA.

Upstream configuration

📘

In this document, "upstream services" refers to the service(s) that listen for incoming requests. This could be the service itself or a reverse proxy.

The upstream services must:

• Be configured to accept HTTPS connections.
• Use certificates and keys issued by the upstream CA.
• Require a client certificate from incoming requests.
• Validate client certificates using the gateway CA certificate.

The specific configuration depends on the upstream service in use.

For example, in NGINX, client certificate validation is configured as follows:

ssl_client_certificate /path/to/gateway-ca.crt;
ssl_verify_client on;

🚧

When configuring upstream services behind the Login Gateway, ensure that redirect responses from the upstream server use relative paths (e.g., /dashboard) instead of full URLs that include the domain (for example, https://example.com/dashboard). Absolute URLs can bypass the gateway and break the proxy flow, while relative paths ensure that redirection is properly handled through the gateway.

Gateway configuration

To enable mTLS on the Strivacity Login Gateway, the gateway must be provided with:

• A gateway certificate and key issued by the gateway CA.
• The upstream CA certificate to verify the upstream service.

These certificates and keys must be stored as files accessible to the gateway. In containerized systems, they are typically shared with a mounted storage volume, but any solution where the necessary files are on the running container's file system is sufficient.

These files must be configured with the gateway. This can be done via environment or via configuration values.

Configuration via environment variables

Set the following environment variables:

# this is for the upstream CA
      SERVICE_BINDING_ROOT: /opt/certs/bindings

      # Configure mtls for upstream connection
      SPRING_CLOUD_GATEWAY_HTTPCLIENT_SSL_SSL_BUNDLE: mtls
      SPRING_SSL_BUNDLE_PEM_MTLS_KEYSTORE_PRIVATE_KEY: file:/opt/certs/bridge/bridge.key
      # SPRING_SSL_BUNDLE_PEM_MTLS_KEYSTORE_PRIVATE_KEY_PASSWORD: password if the bridge.key has a password
      SPRING_SSL_BUNDLE_PEM_MTLS_KEYSTORE_CERTIFICATE: file:/opt/certs/bridge/bridge.crt

Configuration via Application YAML

Alternatively, configure mTLS in the application YAML file:

spring:
  ssl:
    bundle:
      pem:
        mtls:
          keystore:
            certificate: file:/opt/certs/bridge/bridge.crt
            private-key: file:/opt/certs/bridge/bridge.key
            # private-key-password: [bridge.key’s password, if set]

🚧

The SERVICE_BINDING_ROOT variable has no equivalent YAML setting and must be set via environment variables.

Required certificate files

The following files must be stored in /opt/certs/bindings:

• The upstream CA certificate (filename does not matter).
• A file named type containing the string: ca-certificates

The keystore files are the gateway’s certificate and key.