Skip to main content

Securing the connection between client and Outway

The Outway is a proxy that sets up a connection to a service according to the FSC specification. By default the Outway runs without TLS and without authorization.

There are three options for securing the connection between client and Outway:

  • TLS, so that clients can trust they are actually talking to the Outway.
  • mTLS, using an Nginx sidecar, so that the Outway also only accepts clients that present a trusted client certificate.
  • A Policy Decision Point (PDP), which authorizes the client using the Outway.

TLS and mTLS are alternatives: choose one of the two. The PDP does not depend on either, so you can combine it with TLS, with mTLS, or use it on its own, depending on what your deployment needs. The sections below describe each option on its own.

Configuring TLS on the Outway​

This guide covers enabling TLS on the Outway's client-facing listener — the hop between your own applications and the Outway.

What you get​

  • TLS 1.2 as the minimum version, with the Mozilla intermediate cipher list
  • Server authentication only. The Outway never requests or verifies a client certificate.

Certificate requirements​

  • PEM-encoded certificate and private key, loaded as a standard key pair at startup.
  • If your leaf is signed by an intermediate, concatenate the chain into the certificate file, leaf first.
  • The SAN must include the hostname clients use to reach the Outway.
  • Do not reuse the FSC group certificate here. It works technically, but it ties your FSC identity to an internal-facing listener. Issue a separate certificate from your internal CA (or a public one, if the Outway is reachable from outside).

Key file permissions​

The Outway warns at startup when a private key is world-writable, world-readable, or executable. 0640 and 0600 both pass; 0644 does not. This check runs on the group and internal keys only, but hold the server key to the same standard.


Kubernetes (Helm)​

Below you will see two examples. One uses inline PEM to provide the certificate and private key, the other uses an existing secret. Only the relevant values are included.

Using an inline PEM:

https:
enabled: true
keyPEM: |
-----BEGIN RSA PRIVATE KEY-----
................................................................
-----END RSA PRIVATE KEY-----
certificatePEM: |
-----BEGIN CERTIFICATE-----
................................................................
-----END CERTIFICATE-----

Using an existing secret:

https:
enabled: true
existingSecret:
name: outway-server-tls
keyCertificate: tls.crt
keyPrivateKey: tls.key

Relevant Helm chart values:​

ValueDefaultDescription
https.enabledfalseenables TLS, when true a server certificate and key must be provided
https.existingSecret.name(empty)The name of the secret containing the certificate and private key
https.existingSecret.keyCertificatetls.crtThe key in the secret that contains the certificate
https.existingSecret.keyPrivateKeytls.keyThe key in the secret that contains the private key
https.keyPEM(empty)inline PEM-encoded key
https.certificatePEM(empty)inline PEM-encoded certificate

What the chart changes for you​

Turning on https.enabled flips several things at once:

  • Container port 8080 (named http) becomes 8443 (named https).
  • LISTEN_ADDRESS becomes 0.0.0.0:8443 and LISTEN_HTTPS becomes 1.
  • The Secret is mounted read-only at /certificate-server, and TLS_SERVER_CERT / TLS_SERVER_KEY point into it.
  • The Service exposes service.httpsPort (default 443) named https instead of service.httpPort named http.

Docker​

The Outway image docker.io/federatedserviceconnectivity/outway runs as UID 10001. We want to mount the certificate material as read-only and make sure that UID 10001 can read it.

Restrict the file permissions:

chmod 0640 server-key.pem server-cert.pem

Set the ownership to UID 10001:

sudo chown 10001:10001 server-key.pem server-cert.pem

Docker Compose​

Below you see a Docker Compose setup that has enabled TLS on the Outway, only the relevant environment flags are included.

This guide expects server-key.pem and server-cert.pem to be present in the folder ./certs

services:
outway:
image: docker.io/federatedserviceconnectivity/outway:latest
ports:
- "8443:8443"
volumes:
- ./certs:/certs:ro
environment:
LISTEN_ADDRESS: 0.0.0.0:8443
LISTEN_HTTPS: "1"
TLS_SERVER_CERT: /certs/server-cert.pem
TLS_SERVER_KEY: /certs/server-key.pem

Relevant environment values​

Environment variableDefaultDescription
LISTEN_HTTPSfalseenables TLS, when true TLS_SERVER_CERT and TLS_SERVER_KEY are required
TLS_SERVER_CERT(empty)Path to a PEM-encoded certificate
TLS_SERVER_KEY(empty)Path to a PEM-encoded key
LISTEN_ADDRESS127.0.0.1:8080Listen address of the Outway

Verifying​

Check the startup log of the Outway first. You want to see:

starting HTTPS server on 0.0.0.0:8443

If it says starting HTTP server, LISTEN_HTTPS did not take effect. In this case you should check the LISTEN_HTTPS flag.

Then, from a client:

# Inspect the presented chain
openssl s_client -connect outway.example.org:8443 -servername outway.example.org </dev/null

# Confirm the listener answers over TLS
curl -v --cacert internal-ca.pem https://outway.example.org:8443/health/live

A 200 from /health/live over HTTPS means the listener is up with a chain your client trusts. If you do not receive a 200 status code you should check the relevant environment values.

Configuring mTLS with an Nginx sidecar​

The Outway's own TLS listener only authenticates the server: it never asks for a client certificate. To require clients to present one, run an Nginx sidecar in the Outway pod. The sidecar terminates mTLS on port 8443, checks the client certificate, and proxies the request to the Outway, which listens on 127.0.0.1:8080 only.

Use this instead of the Outway's built-in TLS: leave https.enabled (or LISTEN_HTTPS) off, because the sidecar terminates TLS.

Conventions used in the examples​

ItemValue
Outway namespacefsc
Outway Helm releaseoutway (so pod labels are app.kubernetes.io/name: open-fsc-outway, app.kubernetes.io/instance: outway)
Hostname clients useoutway-mtls.fsc.svc.cluster.local
Allowed clienta certificate with common name example-client.outway-client
Internal CAthe cert-manager Issuer named internal from the Helm installation guide

Kubernetes (Helm)​

1. Issue a server certificate for the sidecar​

The sidecar needs a server certificate. In this example we use outway-mtls.fsc.svc.cluster.local which is the Kubernetes Service name. As with built-in TLS, do not reuse the FSC group certificate here.

outway-mtls-server-certificate.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: outway-mtls-server-tls
namespace: fsc
spec:
commonName: outway-mtls.fsc.svc.cluster.local
dnsNames:
- outway-mtls.fsc.svc.cluster.local
- outway-mtls.fsc.svc
- outway-mtls
issuerRef:
name: internal
duration: 2160h # 90 days
renewBefore: 720h # 30 days
secretName: outway-mtls-server-tls
usages:
- digital signature
- key encipherment
- server auth
privateKey:
size: 4096
rotationPolicy: Always

Apply outway-mtls-server-certificate.yaml

kubectl apply -f outway-mtls-server-certificate.yaml
kubectl get certificate -n fsc outway-mtls-server-tls

The resulting secret holds tls.crt, tls.key and ca.crt. The sidecar uses ca.crt to check client certificates, so clients must get their certificates from the same CA.

2. Issue a client certificate​

Each client that may use the Outway needs a client certificate with the client auth usage. The example below issues one for a single client.

outway-client-certificate.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: outway-client-example-tls
namespace: fsc
spec:
commonName: example-client.outway-client
issuerRef:
name: internal
duration: 2160h # 90 days
renewBefore: 720h # 30 days
secretName: outway-client-example-tls
usages:
- digital signature
- key encipherment
- client auth
privateKey:
size: 4096
rotationPolicy: Always

Apply outway-client-certificate.yaml

kubectl apply -f outway-client-certificate.yaml
kubectl get certificate -n fsc outway-client-example-tls

The client application mounts tls.crt and tls.key as its client certificate and trusts ca.crt to verify the sidecar. If the client runs in another namespace, issue the certificate there, using an issuer (for example a ClusterIssuer) backed by the same CA.

3. Create the sidecar configuration​

Create a ConfigMap that contains the Nginx configuration for the mTLS listener.

Two settings decide who gets in, and both are needed:

  • ssl_verify_client on with ssl_client_certificate — Nginx rejects any connection without a valid client certificate from the internal CA.
  • The map on $ssl_client_s_dn — trusting the CA alone is not enough. The map pins the subjects that may use the Outway.

The remaining settings keep the sidecar as transparent as the Outway itself:

  • client_max_body_size 0, proxy_request_buffering off and proxy_buffering off — Nginx otherwise rejects request bodies over 1 MB and buffers requests and responses, which caps uploads and stalls streaming responses.
  • keepalive in the upstream block together with proxy_set_header Connection "" — both are needed to reuse connections to the Outway.

nginx-outway-mtls-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
name: outway-mtls
namespace: fsc
data:
outway-mtls.conf: |
# Subjects of the client certificates that may use the Outway.
map $ssl_client_s_dn $client_allowed {
default 0;
"CN=example-client.outway-client" 1;
}

upstream outway {
server 127.0.0.1:8080;
keepalive 32;
}

server {
listen 8443 ssl;
server_name _;

ssl_certificate /tls/server/tls.crt;
ssl_certificate_key /tls/server/tls.key;
ssl_protocols TLSv1.2 TLSv1.3;

# Require a client certificate signed by the internal CA.
ssl_client_certificate /tls/server/ca.crt;
ssl_verify_client on;
ssl_verify_depth 2;

# A valid certificate is not enough: only listed subjects may pass.
if ($client_allowed = 0) {
return 403;
}

client_max_body_size 0;
proxy_request_buffering off;
proxy_buffering off;

location / {
proxy_pass http://outway;

proxy_set_header Host $host;

# Required for upstream keepalive: nginx sends "Connection: close"
# to the upstream unless this header is cleared.
proxy_set_header Connection "";

proxy_http_version 1.1;
proxy_connect_timeout 10s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}

Apply nginx-outway-mtls-configmap.yaml

kubectl apply -f nginx-outway-mtls-configmap.yaml

Mounting the ConfigMap over /etc/nginx/conf.d replaces the image's default.conf, which would otherwise listen on port 8080 and collide with the Outway.

4. Add the sidecar to the Outway deployment​

outway-values-mtls.yaml

extraContainers:
- name: outway-mtls
# Pin a digest in production; this tag is here for readability.
image: nginxinc/nginx-unprivileged:1.27-alpine
imagePullPolicy: IfNotPresent
ports:
- name: outway-mtls
containerPort: 8443
protocol: TCP
securityContext:
allowPrivilegeEscalation: false
runAsNonRoot: true
runAsUser: 101
capabilities:
drop:
- "ALL"
volumeMounts:
- name: outway-mtls-config
mountPath: /etc/nginx/conf.d
readOnly: true
- name: outway-mtls-server-tls
mountPath: /tls/server
readOnly: true
resources:
requests:
cpu: 25m
memory: 32Mi
limits:
memory: 128Mi

extraVolumes:
- name: outway-mtls-config
configMap:
name: outway-mtls
defaultMode: 0440
- name: outway-mtls-server-tls
secret:
secretName: outway-mtls-server-tls
defaultMode: 0640

Merge outway-values-mtls.yaml into your outway-values.yaml and upgrade the Outway Helm deployment. Make sure https.enabled is false.

helm upgrade outway oci://registry-1.docker.io/federatedserviceconnectivity/open-fsc-outway \
-n fsc -f outway-values.yaml -f outway-values-mtls.yaml

5. Expose the sidecar​

The chart's own Service points at the Outway's http but we need to use the https port exposed by the sidecar. Create a Service that points at the sidecar instead.

outway-mtls-service.yaml

apiVersion: v1
kind: Service
metadata:
name: outway-mtls
namespace: fsc
spec:
type: ClusterIP
selector:
app.kubernetes.io/name: open-fsc-outway
app.kubernetes.io/instance: outway
ports:
- name: https
port: 443
targetPort: outway-mtls
protocol: TCP

Apply outway-mtls-service.yaml

kubectl apply -f outway-mtls-service.yaml

Clients now reach the Outway at https://outway-mtls.fsc.svc.cluster.local.

Verifying mTLS on Kubernetes​

Check that the sidecar started without errors:

kubectl logs -n fsc deploy/outway-open-fsc-outway -c outway-mtls

Then fetch the client certificate and forward the Service to your machine:

kubectl get secret -n fsc outway-client-example-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > client.crt
kubectl get secret -n fsc outway-client-example-tls -o jsonpath='{.data.tls\.key}' | base64 -d > client.key
kubectl get secret -n fsc outway-client-example-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

kubectl port-forward -n fsc service/outway-mtls 8443:443

In a second terminal, replace <grant-hash> with a grant-hash of a ServiceConnectionGrant of a valid Contract and run the two checks below.

A request without a client certificate is rejected by the sidecar with a 400 and the message No required SSL certificate was sent:

curl --cacert ca.crt \
--resolve outway-mtls.fsc.svc.cluster.local:8443:127.0.0.1 \
https://outway-mtls.fsc.svc.cluster.local:8443/ \
-H 'Fsc-Grant-Hash: <grant-hash>'

A request with the client certificate reaches the Outway and returns a response from the API exposed through FSC:

curl --cacert ca.crt --cert client.crt --key client.key \
--resolve outway-mtls.fsc.svc.cluster.local:8443:127.0.0.1 \
https://outway-mtls.fsc.svc.cluster.local:8443/ \
-H 'Fsc-Grant-Hash: <grant-hash>'

Configuring a Policy Decision Point (PDP)​

It is possible to configure a Policy Decision Point (PDP) on the Outway. The rest of the documentation calls the PDP an authorization service; the two (PDP and authorization service) are the same thing. Setup authorization describes what the Outway sends it, the interface it must implement, and how to do the same for an Inway. This section walks through a concrete example.

The PDP will be called for each request going through the Outway, the PDP decides if the request is authorized and the Outway enforces the decision of the PDP.

In the example below we will use Open Policy Agent (OPA) as a PDP. We will create a policy that expects an API key to be present in the HTTP header Authorization. If the API key is present and matches with the expected API key very-secret-api-key, the request will be authorized.

The Policy:

package httpapi.outway

import rego.v1

default allow := {
"allowed": false,
"status": {"reason": "permission denied authorization header does not contain a valid api key"},
}

allow := {"allowed": true, "status": {"reason": reason}} if {
valid_api_key
reason := "authorization header contains a valid api key"
}

valid_api_key if {
input.headers["Authorization"][0] == "very-secret-api-key"
}

In our example OPA runs on https://opa-service.example.com and it provides TLS using a certificate signed by an internal CA.

Kubernetes (Helm)​

In our case OPA provides TLS using a certificate that is signed by an internal CA. The certificate of the CA must be present as a Kubernetes secret.

Kubernetes Secret containing the CA certificate:

apiVersion: v1
kind: Secret
metadata:
name: ca-root-certificate
type: Opaque
stringData:
ca.crt: |
-----BEGIN CERTIFICATE-----
................................................................
-----END CERTIFICATE-----

Outway chart values, only the relevant values are included:

config:
authorizationService:
enabled: true
url: https://opa-service.example.com/v1/data/httpapi/outway/allow
caCertificatePEMExistingSecret:
name: ca-root-certificate
key: ca.crt

Relevant Helm chart values​

ValueDefaultDescription
config.authorizationService.enabledfalseWhen true, the Outway will use the authorization service
config.authorizationService.url(empty)URL of the authorization service
config.authorizationService.caCertificatePEMExistingSecret.name(empty)The name of the secret containing the certificate
config.authorizationService.caCertificatePEMExistingSecret.keyca.crtThe key in the secret that contains the certificate
config.authorizationService.withBodyfalseWhen true the request to the authorization server will contain the body of the original request
config.authorizationService.maxBodySize4096The maximum request body size in bytes that is allowed. If a body exceeds this limit, the request will fail
config.authorizationService.maxChunkSize1024The chunk size in bytes that is used to process each request body chunk

Docker compose​

Below you see a Docker Compose setup that has OPA configured as authorization server, only the relevant environment values are included.

Note that AUTHORIZATION_SERVICE_ADDRESS is the full URL of the decision rule, not the base URL of OPA. For the policy above that is /v1/data/httpapi/outway/allow.

This guide expects root-ca.pem to be present in the folder ./certs

services:
outway:
image: docker.io/federatedserviceconnectivity/outway:latest
volumes:
- ./certs:/certs:ro
environment:
AUTHORIZATION_SERVICE_ADDRESS: https://opa-service.example.com/v1/data/httpapi/outway/allow
AUTHORIZATION_ROOT_CA: /certs/root-ca.pem

Relevant environment values​

Environment variableDefaultDescription
AUTHORIZATION_SERVICE_ADDRESS(empty)The address of the authorization server
AUTHORIZATION_ROOT_CA(empty)Path to a PEM-encoded certificate, only needed when the authorization server provides TLS

Verifying​

  • Replace <outway-address> with the address of your Outway
  • Replace <grant-hash> with a grant-hash of a ServiceConnectionGrant of a valid Contract

Calling the Outway without the Authorization header should fail.

curl <outway-address> -H 'Fsc-Grant-Hash: <grant-hash>'

The response should have an HTTP status 401 with the message authorization service denied request

Calling the Outway with the Authorization header should succeed.

curl <outway-address> -H 'Fsc-Grant-Hash: <grant-hash>' -H 'Authorization: very-secret-api-key'

This should return a response from the API exposed through FSC.