What is an SSH Tunnel in SurveyAnalytica?

An SSH tunnel connection allows SurveyAnalytica to securely access resources in your private network by establishing an encrypted SSH tunnel through a jump server (also known as a bastion host). This is commonly used when you need SurveyAnalytica to connect to internal databases, APIs, or services that are not directly reachable from the internet, but are accessible from a server that does have SSH exposed.

SSH tunnels are a lightweight alternative to VPN connections and are well-suited for connecting to individual services such as a database on a specific host and port.

Prerequisites

Before configuring an SSH tunnel connection, ensure you have the following:

• A jump server (bastion host) with SSH access that is reachable from the internet on a known port (typically port 22).
• Port forwarding enabled on the jump server. The SSH server configuration (/etc/ssh/sshd_config) must allow AllowTcpForwarding yes.
• Network connectivity from the jump server to the target internal resource (e.g., a database at 10.0.1.50:5432).
• A user account on the jump server for SurveyAnalytica to authenticate with.
• Administrative access to add SSH public keys to the jump server.

Step 1: Generate an SSH Key Pair

SurveyAnalytica uses key-based authentication for SSH tunnels. Generate a dedicated key pair for this connection using the following command:

ssh-keygen -t ed25519 -C "surveyanalytica-tunnel"

When prompted:

• Save the key to a file (e.g., ~/.ssh/surveyanalytica_tunnel).
• Optionally set a passphrase (leave empty for automated connections).

This generates two files:

• surveyanalytica_tunnel — The private key (you will paste this into SurveyAnalytica).
• surveyanalytica_tunnel.pub — The public key (you will install this on your jump server).

Note: We recommend Ed25519 keys for their strong security and compact size. RSA keys (4096-bit) are also supported.

Step 2: Authorize the Key on the Jump Server

The public key must be added to the authorized keys on your jump server. You can do this using ssh-copy-id:

ssh-copy-id -i ~/.ssh/surveyanalytica_tunnel.pub username@jump-server-host

Alternatively, manually append the public key to the authorized keys file:

cat ~/.ssh/surveyanalytica_tunnel.pub | ssh username@jump-server-host "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Or, if you have direct access to the server, open ~/.ssh/authorized_keys on the jump server and paste the contents of the .pub file on a new line.

Verify the key works before proceeding:

ssh -i ~/.ssh/surveyanalytica_tunnel username@jump-server-host echo "Connection successful"

Step 3: Configure the SSH Tunnel in SurveyAnalytica

In SurveyAnalytica, navigate to Settings → Network Connections and click Add Connection. Select SSH Tunnel as the connection type.

Fill in the following fields:

Jump Server Settings

Field	Description	Example
Host	The public hostname or IP address of your jump server	bastion.example.com
Port	The SSH port on the jump server	22
Username	The SSH user account on the jump server	sa-tunnel
Private Key	Paste the contents of the private key file	Contents of surveyanalytica_tunnel

Target Service Settings

Field	Description	Example
Remote Host	The internal hostname or IP of the target resource (as seen from the jump server)	10.0.1.50
Remote Port	The port of the target service	5432

Click Test Connection to verify that SurveyAnalytica can establish the tunnel and reach the target service. If successful, click Save.

How It Works

When an integration or workflow needs to reach your internal resource, SurveyAnalytica:

1. Opens an SSH connection to your jump server using key-based authentication.
2. Establishes an encrypted tunnel (SSH port forwarding) from SurveyAnalytica to the target host and port via the jump server.
3. Routes integration traffic through this tunnel to reach the internal service.
4. Closes the tunnel when the operation completes.

Security Best Practices

• Use a dedicated user account: Create a specific user (e.g., sa-tunnel) on the jump server for SurveyAnalytica. Do not use root or shared accounts.
• Restrict to port forwarding only: Configure the SSH user to allow only port forwarding, not interactive shell access. Add the following to ~/.ssh/authorized_keys before the key:

  no-pty,no-agent-forwarding,no-X11-forwarding,permitopen="10.0.1.50:5432" ssh-ed25519 AAAA... surveyanalytica-tunnel

  This restricts the key to forwarding traffic only to the specified host and port.

• Use key-based authentication only: Disable password authentication for the tunnel user. In /etc/ssh/sshd_config, ensure:

  Match User sa-tunnel
      PasswordAuthentication no
      AllowTcpForwarding yes
      PermitTunnel no
      X11Forwarding no

• Rotate keys periodically: Generate a new key pair and update both SurveyAnalytica and the jump server every 180 days.
• Monitor access: Review SSH login logs on your jump server regularly for unexpected access patterns.
• Restrict source IPs: If your jump server supports it, restrict SSH access to SurveyAnalytica’s egress IP ranges (available upon request from support).

Troubleshooting

Connection Refused

• Verify the jump server host and port are correct and the SSH service is running.
• Check that your firewall allows inbound SSH connections from SurveyAnalytica’s IP ranges.

Authentication Failed

• Confirm the public key has been added to ~/.ssh/authorized_keys on the jump server.
• Verify the private key pasted into SurveyAnalytica matches the public key on the server.
• Check file permissions: ~/.ssh should be 700, authorized_keys should be 600.

Tunnel Established but Target Unreachable

• From the jump server, verify you can reach the target: nc -zv 10.0.1.50 5432.
• Check that AllowTcpForwarding is set to yes in the SSH server configuration.
• Ensure the permitopen restriction (if used) includes the correct target host and port.