Duo Unix - Two-Factor Authentication for SSH (login_duo)

Overview

Duo can be enabled on any Unix system with the addition of a simple login_duo utility. We recommend deploying our pam_duo module with Pluggable Authentication Modules (PAM) support instead of login_duo in most scenarios for the most secure and customizable experience, especially if port forwarding and tunneling is used in your environment.

Walkthrough Video

First Steps

Before starting:

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications.
3. Click Protect an Application and locate UNIX Application in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. See Getting Started for help.

Installation

FIPS Support

Duo Unix is FIPS-compliant as of version 1.10.4 when run on any machine that has an operating system-wide FIPS mode (like Centos/RedHat 7, Ubuntu 16.04, etc.). No additional flags or options are required.

Install login_duo Prerequisites

OpenSSL development headers and libraries are required for login_duo. When compiling on SUSE/SLES, the zlib package is also necessary.

You also need a compiler like gcc installed on your system to build Duo Unix.

Install login_duo

Once the required dependencies are built and installed, download, build, and install duo_unix.

1. Download and extract the latest version of duo_unix (checksum). Change to the extracted directory (note your actual extracted directory name reflects the actual version downloaded; the example syntax below references version 1.11.2). View checksums for Duo downloads here.

   $ wget https://dl.duosecurity.com/duo_unix-latest.tar.gz
   $ tar zxf duo_unix-latest.tar.gz
   $ cd duo_unix-1.11.2
   

2. Build and install duo_unix.

   $ ./configure --prefix=/usr && make && sudo make install

   For advanced build options, see the README file in the source tarball.

3. Once duo_unix is installed, edit login_duo.conf (in /etc/duo or /etc/security) to add the integration key, secret key, and API hostname from your Duo Unix application.

   [duo]
   ; Duo integration key
   ikey = INTEGRATION_KEY
   ; Duo secret key
   skey = SECRET_KEY
   ; Duo API hostname
   host = API_HOSTNAME

4. You may also add optional Duo configuration options to login_duo.conf. See the table in Duo Configuration Options for all available settings.

Test login_duo

As a regular user, test login_duo manually by running

$ /usr/sbin/login_duo

On some systems, you may instead have to run /usr/local/sbin/login_duo.

If everything is set up correctly, you'll be given an enrollment link and prompted to enroll:

Visit the URL, enroll your phone, and then try login_duo again, this time adding a command to run after authentication is complete:

$ /usr/sbin/login_duo echo 'YOU ROCK!'

You should see something like this:

If you are having trouble with these steps, or if you aren't getting a Duo login prompt, try running login_duo with the -d flag to enable debug output.

Enable login_duo

To protect remote access via SSH, use login_duo.

To enable two-factor authentication for any SSH login method (password, pubkey, etc.) for any user, edit your sshd_config (usually in /etc or /etc/ssh) to add the following line:

ForceCommand /usr/sbin/login_duo

This ForceCommand directive instructs sshd to run login_duo (to perform two-factor authentication) before any other requested commands. However, according to the sshd documentation: "The command is invoked by using the user's login shell with the -c option." This means that shell rc files (e.g. .bashrc, .cshrc, etc.) execute before login_duo; if users can edit these files, they may be able to disable Duo authentication for their own accounts. Keep in mind that ForceCommand also disables command=. Mitigate these issues by deploying pam_duo instead of login_duo.

We strongly recommend that you disable PermitTunnel and AllowTcpForwarding in your sshd_config when using login_duo to protect SSH logins. Since OpenSSH sets up port forwarding and tunneling before Duo's two-factor challenge, an attacker may be able to access internal services via port forwarding before completing secondary authentication. Adding the following lines to your sshd_config will prevent this scenario:

PermitTunnel no
AllowTcpForwarding no

You can also optionally limit two-factor authentication to a subset of users whose primary or supplementary group is specified in login_duo.conf. For example:

group = wheel

If you'd like to enable Duo only for specific accounts using SSH pubkeys, use the command option in those users' authorized_keys instead. For example, to verify each admin authorized to log into a shared root account, your ~/.ssh/authorized_keys might look something like this:

command="/usr/sbin/login_duo -f user1" ssh-dss FRP...FD== user1@company
command="/usr/sbin/login_duo -f user2" ssh-dss YUX...IO== user2@company

Now restart the SSH service.

This also works for user-local installations (e.g. in $HOME/bin) without root access — just specify the location of login_duo.conf with the -c flag.

Linux Distribution Packages

To more easily install and maintain Duo Unix deployments, we've built Linux packages for a variety of popular distributions. These packages are tested against the specific listed versions of their respective distributions. Please test all packages thoroughly prior to deploying them into your environment to ensure a great experience.

The Duo GPG key available prior to August 27, 2018 has an expiration date of September 4th, 2018. You can identify this key by looking for the string Version: GnuPG v1.4.5 (GNU/Linux). If you have the old GPG key, be sure to download the new GPG key before downloading updated packages. The new GPG key contains the string Version: GnuPG v2.0.22 (GNU/Linux).

[duosecurity]
name=Duo Security Repository
baseurl=http://pkg.duosecurity.com/CentOS/$releasever/$basearch
enabled=1
gpgcheck=1

# rpm --import https://duo.com/RPM-GPG-KEY-DUO
# yum install duo_unix

deb http://pkg.duosecurity.com/Ubuntu precise main

deb http://pkg.duosecurity.com/Ubuntu trusty main

# curl -s https://duo.com/APT-GPG-KEY-DUO | sudo apt-key add -
# apt-get update && apt-get install duo-unix

[duosecurity]
name=Duo Security Repository
baseurl=http://pkg.duosecurity.com/RedHat/$releasever/$basearch
enabled=1
gpgcheck=1

# rpm --import https://duo.com/RPM-GPG-KEY-DUO
# yum install duo_unix

deb http://pkg.duosecurity.com/Debian squeeze main

deb http://pkg.duosecurity.com/Debian wheezy main

deb http://pkg.duosecurity.com/Debian jessie main

deb http://pkg.duosecurity.com/Debian stretch main

# curl -s https://duo.com/APT-GPG-KEY-DUO | sudo apt-key add -
# apt-get update && apt-get install duo-unix

Troubleshooting

Need some help? Take a look at the Duo UNIX Frequently Asked Questions (FAQ) page or try searching our Duo UNIX Knowledge Base articles or Community discussions. For further assistance, contact Support.

Duo Configuration Options

The login_duo.conf configuration files use the INI format. It can take the following options:

groups = users,!wheel,!*admin guests

Example configuration file with additional options:

[duo]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=X1hXztPX1rb1X71x1wXkpnmXXvqXXXqqj1XoXbbXu
host=api-xxxxxxxx.duosecurity.com
pushinfo=yes
autopush=yes

For more information, see the man page for login_duo.

Network Diagram

1. SSH connection initiated
2. Primary authentication
3. Duo Unix connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service
5. Duo Unix receives authentication response
6. SSH session logged in