If a database is in private subnet in your Microsoft Azure account, you can use an SSH tunnel to connect Stitch. The approach in this tutorial will use a publicly accessible virtual machine, or SSH server, instance to create the connection. The SSH server will act as an intermediary, forwarding the traffic from Stitch through an encrypted tunnel to the database in the private subnet.

The approach outlined in this guide is applicable to the integrations and destinations listed in the next section.

Before you get started, note that an SSH tunnel isn’t necessarily more secure than a direct connection. An SSH tunnel is only as secure as the monitoring and hardening you perform on the SSH server hosting the tunnel.

If you have questions or concerns about Stitch security, refer to the Security FAQ.

Databases this guide applies to

This guide is applicable to the following integrations and destinations:

Integrations Destinations

For SSH for Amazon-hosted databases, refer to the SSH for Amazon guide.

For SSH for self-hosted databases, refer to the SSH for self-hosted databases guide.

Prerequisites

  • Privileges in Microsoft Azure that allow you to:

    • Create/manage virtual machines. This is required to create the SSH server.
    • Create/manage security groups. This is required to enable access between Stitch, the SSH server, and the database.

  • Some familiarity with Linux and the command line. In this tutorial, you’ll create a Linux user for Stitch to ensure access via SSH. While we’ve provided the commands you’ll need to create the user, you should know how to access a server using the command line and feel comfortable running commands.

  • An SSH client, if using a Windows operating system. Some versions of Windows don’t include SSH commands, so you may need to install a Windows-based SSH client before proceeding. Windows 10, however, does include OpenSSH, which is suitable for this tutorial.

    Alternatively, you can use the SSH utilities available in Bash in the Azure Cloud Shell. Note that this approach requires an Azure file share and a new storage account. Refer to Microsoft’s documentation for more info.

Step 1: Verify your Stitch account's data pipeline region

First, you’ll log into Stitch and verify the data pipeline region your account is using. Later in this guide, you’ll need to grant Stitch access to the SSH server by whitelisting our IP addresses.

The IP addresses you’ll whitelist depend on the Data pipeline region your account is in.

  1. Sign into your Stitch account, if you haven’t already.
  2. Click User menu (your icon) > Edit User Settings and locate the Data pipeline region section to verify your account’s region.

  3. Locate the list of IP addresses for your region:

Keep this list handy - you’ll need it later.

Step 2: Create and configure a virtual machine

Next, you’ll create a virtual machine to serve as the SSH server. This publicly accessible instance will act as an intermediary, forwarding the traffic from Stitch through an encrypted tunnel to your private instance.

Step 2.1: Configure the virtual machine's basic settings

  1. Log into your Microsoft Azure account.
  2. In the search bar at the top of the page, type virtual machines.
  3. Click the Virtual machines result.
  4. On the Virtual machines page, click the + Add button.
  5. Fill in the fields in the Basics tab as needed.
  6. When finished, click the Networking tab.

Step 2.2: Configure the virtual machine's networking settings

Next, you’ll create a network security group that will allow inbound traffic from Stitch’s IP addresses.

  1. In the Virtual network field, select the virtual network you want to associate with the virtual machine.
  2. In the Subnet field, select the public subnet you want to associate with the virtual machine.
  3. In the Public IP field, verify that a value other than None is selected. This is required to allow Stitch to successfully connect to the virtual machine.
  4. For NIC network security group, select Advanced. This will display the Configure network security group field.
  5. Click the Create new link under the Configure network security group field. This will open the Create network security group panel.
  6. In the panel, click the + Add an inbound rule link in the Inbound rules section. This will open the Add inbound security rule panel.

  7. Fill in the fields as follows. If a field isn’t in this list, use the default value:

    • Source: Select IP Addresses.

    • Source IP addresses/CIDR ranges: Paste a comma-delimited list of the Stitch IP addresses for your Stitch data pipeline region that you retrieved in Step 1.

      Note: You may also want to add your own IP address(es) to this list. This ensures that you’ll also be able to connect to the database via the virtual machine as needed.

    • Source port ranges: Enter 22.
    • Protocol: Select TCP.
    • Action: Select Allow.
    • Name: Enter a name. For example: stitch-inbound.

    Here’s a look at our setup using Stitch’s North America IP address list:

    The Add inbound security rule panel in Azure, highlighted

  8. When finished, click Add to create the inbound rule.

Step 2.3: Launch the virtual machine

  1. After you’ve finished configuring the virtual machine’s networking settings, click the Review + create tab.
  2. Review the settings for the virtual machine, verifying that the Public IP field is not None.
  3. Click Create to launch the virtual machine.

After you click Create, Azure will launch the deployment process for the virtual machine. This may take a few minutes to complete.

Step 3: Enable the SSH server to access the database

Next, you’ll configure the database to allow traffic forwarded from the virtual machine to access the database server. This is accomplished by whitelisting the virtual machine’s private IP address in the server’s firewall settings.

Step 3.1: Retrieve the SSH server's connection details

In this step, you’ll retrieve the SSH server’s public and private IP addresses. The private IP address will be used in the next step, whereas the public IP address will be used to complete the setup in Stitch.

  1. In the sidenav, click Virtual machines.
  2. In the search bar at the top of the page, type virtual machines.
  3. Click the Virtual machines result.
  4. In the list of available virtual machines, click the one you created in Step 2. This will open the instance’s details page.

  5. Locate the Public IP address and Private IP address fields, which are highlighted in the image below:

    The virtual machine details page with the Public and Private IP address fields highlighted

Copy the IP addresses somewhere handy, making sure to note which is public and which is private. Confusing these values will lead to an unsuccessful connection in Stitch.

Step 3.2: Create a server firewall rule for the virtual machine

I'm connecting an integration.

  1. Locate and open the database you want to connect to Stitch.

  2. Click Settings > Connection security.

  3. Create a rule for the virtual machine’s IP address:
    • Rule name: Enter a name for the rule. For example: Stitch VM
    • Start IP: Paste the virtual machine’s private IP address.
    • End IP: Paste the virtual machine’s private IP address again.

    Below is what the rule should look like when finished:

    IP rule for a virtual machine

  4. Click Save.

I'm connecting a destination.

  1. In the sidenav, click SQL databases.
  2. On the page that displays, click the name of the database you want to connect to Stitch.
  3. The details page for the database will display. Click the link in the Server name field.

  4. The details page for the server will display. Click the Show firewall settings link in the Firewalls and virtual networks field.

  5. Create a rule for the virtual machine’s IP address:
    • Rule name: Enter a name for the rule. For example: Stitch VM
    • Start IP: Paste the virtual machine’s private IP address.
    • End IP: Paste the virtual machine’s private IP address again.

    Below is what the rule should look like when finished:

    IP rule for a virtual machine

  6. Click Save.

Step 4: Retrieve your Public Key

The Stitch public key is used to authorize the Stitch SSH user. This key is specific to your Stitch account.

Note: If the key isn’t properly installed, Stitch will be unable to access the server.

To retrieve your public key, use the instructions below:

I'm connecting an integration.

The Stitch Public Key

  1. Sign into your Stitch account, if you haven’t already.
  2. Next:

    • For new integrations: Click Add Integration, locate the type of database you’re connecting on the Integrations page, and click its icon.

    • For existing integrations: Locate and click the integration on the Stitch Dashboard page, then click the Settings tab.

  3. In the Integration Settings page, you’ll see one of two options:

    • SSH Tunnel: Click the checkbox to display the SSH fields.
    • Encryption Type: Click the dropdown and select the SSH Tunnel option to display the SSH fields.
  4. Locate the Public Key field.

Leave this page open for now - you’ll need it the next step.

I'm connecting a destination.

The Stitch Public Key

  1. Sign into your Stitch account, if you haven’t already.
  2. Click the Destination tab at the top of the page.
  3. Click the icon of the destination you’re connecting.
  4. In the Destination Settings page, click the Encryption Type menu, then the SSH Tunnel option. This will display the SSH fields.

  5. In the Integration Settings page, you’ll see one of two options:

    • SSH Tunnel: Click the checkbox to display the SSH fields.
    • Encryption Type: Click the dropdown and select the SSH Tunnel option to display the SSH fields.
  6. Locate the Public Key field.

Leave this page open for now - you’ll need it the next step.

Step 5: Create the Stitch SSH user

Next, you’ll create a Stitch user on the SSH server. This will allow Stitch to authenticate via a public key and connect to the server.

  1. Open a new terminal window and log into your SSH server.

  2. Create a group named stitch:

    sudo groupadd stitch

  3. Create a user named stitch:

    sudo useradd -m -g stitch stitch

  4. Switch to the stitch user:

    sudo su - stitch

  5. Create the .ssh directory:

    mkdir ~/.ssh

  6. Using chmod, alter the permissions of the directory to allow access:

    chmod 700 ~/.ssh

  7. Navigate to the .ssh directory:

    cd ~/.ssh

  8. Using touch, create the authorized_keys file:

    touch authorized_keys

  9. Set the permissions for authorized_keys:

    chmod 600 authorized_keys

  10. Import the Stitch public key into authorized_keys, replacing <PUBLIC KEY> with the public key. Verify after replacing the key that it is on one line and doesn’t contain line breaks:

    echo "<PUBLIC KEY>" >> ~/.ssh/authorized_keys

Step 6: Complete the setup for Stitch

The last step is to complete the setup steps required to connect the database to Stitch. The instructions vary from database to database, and whether the database is an integration (where data is extracted) or a destination (where data is loaded).

Related Troubleshooting
Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.