DuoConnect for SSH Access

DuoConnect lets you easily access your organization’s SSH servers without needing to use a VPN.

DuoConnect is supported on 64-bit versions of Windows, macOS, and Linux systems. To use DuoConnect, you'll need to install the DuoConnect client software on your workstation, then perform some configuration steps for SSH to work. Your Duo administrator will send you the detailed connection information you’ll need to update your SSH connections.

Windows Clients

Install DuoConnect

  1. Download the latest DuoConnect Installer for Windows on your computer while logged in as an administrator.
  2. Double-click the downloaded MSI file to launch the installer.
  3. On the "DuoConnect Setup Wizard" page, click Next.
  4. On the "Destination Folder" page leave the default destination selected and click Next.
  5. Click Install on the "Ready to install DuoConnect" page. If a pop-up appears asking "Do you want to allow the following program to install software on this computer?", click Yes.
  6. Click Finish on the "Completed the DuoConnect Setup Wizard" page to exit the installer.

Configure

Now that you’ve installed DuoConnect, you need to update your SSH client configuration to use it.

PuTTY

  1. Open up PuTTY and load a saved PuTTY session for the SSH server you'll be connecting to with DuoConnect.
  2. Expand the Connection category on the left-hand side of the PuTTY session window, and then click on Proxy. The "Options controlling proxy usage" appear on the right-hand side of the window.
  3. Under "Proxy type" select Local.
  4. Under "Telnet command, or local proxy command" copy and paste in the DuoConnect connection string you received from your Duo administrator.

    Here's an example of what the command might look like:

    duoconnect -host %host:%port -relay=https://server-ssh.example.com
  5. Return to the saved PuTTY session window and click Save to update the session with the DuoConnect information.
  6. Repeat the saved session configuration steps for all SSH servers you will access using DuoConnect.
  7. DuoConnect PuTTY Configuration

Git, Cygwin, and Other OpenSSH based Terminals

  1. Open your ~/.ssh/config file in a text editor. If you don't have this file, create it.
  2. Copy and paste in the DuoConnect connection strings you received from your Duo administrator into the end of your config file.

    Here's an example of what the command might look like:

    Host server.example.com
      ProxyCommand duoconnect -host=%h:%p -relay=https://server-ssh.example.com
  3. Repeat these steps for all SSH servers provided to you by your Duo administrator.
  4. Save the ~/.ssh/config file.

macOS Clients

Install DuoConnect

  1. Download the latest DuoConnect Installer for macOS on your computer while logged in as an administrator.
  2. Double-click the pkg file to launch the installer.
  3. On the "Welcome to the DuoConnect Installer" page, click Continue.
  4. On the "Select a Destination" page leave the default destination selected and click Continue.
  5. Click Install on the "Select Install on HD" page.
  6. When the installer prompts you to enter your username and password, enter the required information and click Install Software.
  7. Click Close on the "The installation was completed successfully" page. When asked if you'd like to move the installer to trash, click Move to Trash to delete the installer package from your system.

Configure SSH

Now that you’ve installed DuoConnect, you need to update your SSH client configuration to use it.

Terminal

  1. Open your ~/.ssh/config file in a text editor. If you don't have this file, create it.
  2. Copy and paste in the DuoConnect connection strings you received from your Duo administrator into the end of your config file.

    Here's an example of what the command might look like:

    Host server.example.com
      ProxyCommand duoconnect -host=%h:%p -relay=https://server-ssh.example.com
  3. Repeat these steps for all SSH servers provided to you by your Duo administrator.
  4. Save the ~/.ssh/config file.

Linux Clients

Install DuoConnect

  1. Download the latest DuoConnect Installer for Linux on your computer while logged in as a user with sudo permission.
  2. Open up a terminal window and navigate to the directory where you downloaded the DuoConnect installer gz file.
  3. In your terminal window type the following command to unpack the installer:

    tar xzvf DuoConnect-1.0.0.tar.gz

    Note that the filename may differ slightly from this example to reflect the most recent version.
  4. You can now run the installer by typing:

    sudo ./install.sh
  5. You'll be asked to enter your password. Upon successful installation you'll see the following:

    + cp duoconnect /usr/local/bin/
    + chmod 755 /usr/local/bin/duoconnect
    + chown 0:0 /usr/local/bin/duoconnect

Configure SSH

Now that you’ve installed DuoConnect, you need to update your SSH client configuration to use it.

Terminal

  1. Open your ~/.ssh/config file in a text editor. If you don't have this file, create it.
  2. Copy and paste in the DuoConnect connection strings you received from your Duo administrator into the end of your config file.

    Here's an example of what the command might look like:

    Host server.example.com
      ProxyCommand duoconnect -host=%h:%p -relay=https://server-ssh.example.com
  3. Repeat these steps for all SSH servers provided to you by your Duo administrator.
  4. Save the ~/.ssh/config file.

Test SSH Login

Once you've installed DuoConnect and updated your SSH client configuration(s), test an SSH connection to make sure everything is working properly.

  1. Start an SSH connection as you normally would to connect to your SSH server.
  2. A browser window will pop-up, prompting you to enter your organizational username and password.
  3. After primary login you'll need to complete Duo two-factor authentication (or enroll yourself in Duo).
  4. The next page instructs you to close the browser tab and return to your SSH client.
  5. You’ll be connected to the SSH server and can then continue with logging in to the remote server like you normally would.

Congratulations! You have successfully accessed your SSH server using DuoConnect!


Updating DuoConnect

We'll periodically release new versions of DuoConnect with new features or functionality, bug fixes, or security patches.

DuoConnect updates are either optional or required. You'll be able to skip an optional update and continue connecting to the remote SSH host, but required updates must be installed before you can access any system.

Optional DuoConnect Updates

If you are not running the latest DuoConnect when attempting to authenticate to an SSH server we'll let you know that your DuoConnect client is out of date.

DuoConnect Optional Update Page

If you click Update Later, you will complete authentication and successfully log in but will be prompted again to update the next time you need to authenticate to an SSH server.

If you click Update Now, you will be taken to a page to download and install the newest version of DuoConnect for your computer platform.

DuoConnect Update Page

After you install the updated DuoConnect client you will need to reauthenticate to the server from your terminal.

Required DuoConnect Updates

If you are not running the minimum required version of DuoConnect when attempting to authenticate to an SSH server, we'll let you know that your DuoConnect client is out of date and that you must update to continue connecting.

DuoConnect Update Page

After you install the updated DuoConnect client you will need to reauthenticate to the server from your terminal.


Frequently Asked Questions

Chrome on macOS opens a blank browser page and doesn't authenticate. What should I do?

There is a macOS issue where Chrome fails to open links correctly with a pending Chrome update. Update and relaunch Chrome to proceed. A fix for this is expected in macOS 10.13.4.

At the beginning of the day, when using VS Code or similar tools, you may see a browser pop-up prompting you for first factor without you initiating a connection.

Your editor is attempting a git fetch every time you go to it. You can disable the auto-fetch feature by changing the following setting: "git.autofetch": false.

You can find more information here: Using Version Control in VS Code.