Deploying Duo Unix on Ubuntu for SSH Two-Factor Authentication

This tutorial shows how to compile and configure Duo Unix to protect SSH logins with system password + Duo Mobile Push.
It covers Duo portal preparation, source installation, and all necessary server-side configuration files.

1. Prepare Duo Admin Portal

1. Create a Unix Application
   • Log in to the Duo Admin Panel → Applications → Protect an Application.
   • Search for Unix Application and click Protect.
   • Note the generated Integration key (ikey), Secret key (skey), and API hostname (host).
2. Create a Duo User
   • Go to Users → Add User.
   • Enter the Linux username (recommended to match the system user).
   • After the user is created, open the user details page and click Add Phone.
   • Add a phone number and select Duo Mobile as the device type.
   • Save and ensure the user status is Active.

2. Compile and Install Duo Unix

sudo apt update
wget --content-disposition https://dl.duosecurity.com/duo_unix-latest.tar.gz
tar zxf duo_unix-*.tar.gz
cd duo_unix-*/

# Install build dependencies
sudo apt install -y build-essential gcc make autoconf automake libtool pkg-config libpam0g-dev libssl-dev

# Configure, build, and install
./configure --with-pam --prefix=/usr
make
sudo make install

After installation you will have:

• pam_duo.so – the PAM module
• login_duo – an optional helper (not used in this guide)

3. Configure /etc/duo/pam_duo.conf

This file defines how the Duo PAM module communicates with Duo’s cloud service.

[duo]
ikey = <Integration key>
skey = <Secret key>
host = <API hostname>

autopush = yes        # Automatically send a Duo Push
prompts  = 1          # Only prompt once
failmode = safe       # If Duo is unreachable, allow login (use 'secure' to block)
pushinfo = yes        # Include username/IP in the push message

Replace the placeholders with the values from the Duo Admin Panel.

4. Configure /etc/ssh/sshd_config

Enable PAM and allow password + keyboard-interactive authentication so that Duo can be invoked.

PasswordAuthentication no
KbdInteractiveAuthentication yes
ChallengeResponseAuthentication yes
UsePAM yes
UseDNS no

Check syntax and restart SSH:

sudo sshd -t
sudo systemctl restart sshd

5. Configure PAM Rules

/etc/pam.d/common-auth

auth    [success=1 default=ignore]      pam_unix.so nullok_secure
auth  requisite pam_unix.so
auth  [success=1 default=ignore] /lib64/security/pam_duo.so
auth  requisite pam_deny.so
auth  required pam_permit.so

/etc/pam.d/sshd

# @include common-auth
auth  required pam_env.so
auth  requisite pam_unix.so
auth  [success=1 default=ignore] /lib64/security/pam_duo.so
auth  requisite pam_deny.so
auth  required pam_permit.so

This ensures that after the primary password check, Duo performs the second-factor verification.

6. Test the Setup

Use any SSH client to connect:

ssh user@your-server

Expected flow:

1. Enter the system password.
2. The server automatically sends a Duo Push to your mobile device.
3. Approve the request in Duo Mobile to complete the login.

Summary

By configuring pam_duo.conf, sshd_config, and common-auth together,
you enable strong two-factor authentication on Ubuntu SSH with a seamless system password + Duo Push workflow.
This setup provides a significant security upgrade while keeping the login process straightforward for users.