Networking

This guide provides a deep-dive into the network configuration options for Sombra.

This guide assumes an understanding of:

• Sombra's purpose (Introduction)
• Sombra's high-level network architecture (Architecture)

Regardless of deployment option, Sombra always hosts a server that handles all communications coming inbound from your internal servers. Transcend should have no access to this server. For more information on this server, see "Sombra serves an API for your client".

The load balancer that you connect to this server can be restricted to the IP ranges that need to communicate with it. When you launch into production, we recommend locking down this server to the minimal set of IP ranges. For Sombra to make an upstream request to Transcend Cloud, your client will need to supply a Transcend-issued API key.

You can require your clients to present a bearer authorization token for an added layer of authentication to Sombra's API.

To generate an INTERNAL_KEY (the bearer token) and INTERNAL_KEY_HASH (what Sombra needs to verify the bearer token):

INTERNAL_KEY_BIN=$(openssl rand 32)
INTERNAL_KEY=$(echo -n "$INTERNAL_KEY_BIN" | base64)
INTERNAL_KEY_HASH=$(echo -n "$INTERNAL_KEY_BIN" | openssl dgst -binary -sha256 | openssl base64)
echo "set in your service environments: INTERNAL_KEY: $INTERNAL_KEY"
echo "set gateway environment: INTERNAL_KEY_HASH: $INTERNAL_KEY_HASH"

To authenticate an internal service to Sombra, pass the header x-sombra-authorization: Bearer ${INTERNAL_KEY}. The hash of this key is stored in the INTERNAL_KEY_HASH environment variable.

To add mutual TLS authentication, you can set:

• TRUSTED_CLIENT_CA_CERT_ENCODED: (optional) The public certificate authority (CA) certificate of a client who can connect to the internal Sombra API over mutual TLS. If set, Sombra will enforce that all incoming requests to non-health routes have a client cert. Like the SOMBRA_TLS_CERT, this is also a base64-encoded string of the PEM-formatted certificate.

You can disable listeners by setting the following ports to undefined. While you can also override the default port numbers, we recommend keeping the default ports to maintain consistency with our other Sombra guides.

• INTERNAL_PORT_HTTPS: Port for the internal HTTPS server (faces inside firewall). Defaults to 5040. Set to undefined if you only want to listen on HTTP. To listen on this HTTPS port, you must also provide SOMBRA_TLS_CERT and SOMBRA_TLS_KEY.
• INTERNAL_PORT_HTTP: Port for the internal HTTP server (faces inside firewall). Defaults to 5039. Set to undefined if you only want to listen on HTTPS. At least one of the above environment variables must be set.
• EXTERNAL_PORT_HTTPS: Port for the external HTTPS server (faces outside firewall). Defaults to 5041. Set to undefined if you only want to listen on HTTP. To listen on this HTTPS port, you must also provide SOMBRA_TLS_CERT and SOMBRA_TLS_KEY. You may ignore this option if using the Reverse Tunnel method.
• EXTERNAL_PORT_HTTP: Port for the external HTTP server (faces outside firewall). Defaults to 5042. Set to undefined if you only want to listen on HTTPS. At least one of the above environment variables must be set. You may ignore this option if using the Reverse Tunnel method.

If you want Sombra to listen over HTTPS (on the ports defined in INTERNAL_PORT_HTTPS and/or EXTERNAL_PORT_HTTPS), you can add TLS certs on Sombra. If you are using the Reverse Tunnel, this is only applicable to the Sombra Customer Ingress. If you are using Direct Connection, this also applies to the external HTTPS server that Transcend will connect to.

• SOMBRA_TLS_CERT: The Sombra TLS Certificate, as a base64 encoded string. This is paired with SOMBRA_TLS_KEY. Either both should be set or neither.
• SOMBRA_TLS_KEY: The TLS private key for this server, base64-encoded in PEM format. Starts with 'LS0tLS1CRUdJT', or in its pre-encoded format, '-----BEGIN'. The pre-encoded string should also include 'PRIVATE KEY-----'. This is paired with SOMBRA_TLS_CERT.
• SOMBRA_TLS_KEY_PASSPHRASE: An optional passphrase associated with your TLS private key. If you set a passphrase when you created your key and certificate, you must provide it here.

Transcend supports three methods of connecting Sombra and Transcend:

1. Reverse Tunnel (recommended): Using the Transcend Sombra Reverse Tunnel.
2. Direct Connection: Setting up public endpoints for the Transcend ingress to your Sombra, and allow-listing inbound connections from Transcend.

The Reverse Tunnel is our recommended method and is configured by default in all of our deployment guides. The Direct Connection method is a legacy option that we continue to support. We only recommend the Direct Connection method if you have company policies which require it, such as established deployment patterns.

This is the default—no action is required. Following any of our deployment guides will set up the Reverse Tunnel out of the box!

If using the Direct Connection deployment method, first decide where you plan to host the gateway. You will need two URLs for both sombra-customer-ingress and sombra-transcend-ingress. For example, this may look something like:

• sombra-transcend-ingress: https://sombra-transcend.acme.com
• sombra-customer-ingress: https://sombra-internal.acme.com:5041

Once you decide on these subdomain names, create a new Sombra gateway in the Sombra settings by clicking the "Create New Self Hosted Sombra" button.

Place a load balancer in front of your Sombra cluster, and point your chosen domain names to the load balancer with TLS certificates that cover those domains.

You can allowlist ingress traffic from Transcend to your Sombra gateway by allowing the following list of IP addresses (Note: all IP addresses need to be allowed):

Follow Configure TLS Certificates to set up your TLS certificate and Configure Ports and Listeners to configure the Sombra's listeners. If your Sombra cluster is deployed behind a load balancer, and you don't want to continue using TLS after the load balancer (thereby using HTTP within your network perimeter), you can omit these environment variables.

The key difference is in the network configuration. The Direct Connection method requires a load balancer, while the Reverse Tunnel does not require you to configure any ingress network policies, as long as the Sombra containers can communicate with the public internet. The tunnel will handle load-balancing among all your running Sombra containers in a round-robin manner.

The Reverse Tunnel method eliminates the need to set up a load balancer, configure TLS (as there is no inbound connection being made), configure DNS, or open up your firewall.

In this picture, you can see the load balancer setup for a Direct Connection Sombra cluster, where our backend talks directly to a load balancer which talks directly to the Sombra cluster.

In this picture, you can see the Reverse Tunnel method, where the Sombra cluster reach out to our backend to establish a private tunnel that our backend can send messages over.

If you are not self-hosting the security gateway, you may want to add IP-restriction on all incoming webhooks and database connections. All traffic will originate from:

Always verify the incoming webhook JWT!

Restricting IP ranges for receiving a webhook is always a great idea; however, you should only use this as a secondary form of authentication. It is crucial that you always verify the incoming webhook signature. Please refer to this guide for information on verifying the webhook signature.