Configuring Duo for SSH access to a linux System

Configuring Duo for SSH access to a linux or unix system

Duo two-factor authentication helps protect ssh services on unix-based systems from unauthorized remote access, by requiring a one-time password in addition to a valid account username and password, or ssh key, for login.  It can optionally be used to protect local logins as well.

For general information about Duo, see our documentation here.

First Steps

  • Contact Information Security by creating a ticket at help.caltech.edu (IMSS/Information Security/Security - General) or by emailing security@caltech.edu to request an integration key, secret key, and API hostname to set up Duo on your system.
  • Information Security will either send you a GPG encrypted file with this information, or a password protected .zip file with the password relayed over the phone.

Please NOTE: Your secret key (skey) is critical to the security of your Duo setup! Secure it as you would any sensitive credential. Don't share it with others or email it unencrypted under any circumstances. If there is ever any doubt as to the security of the secret key, contact Information Security to generate a new one.

Remote login methods: Note that if your system supports other remote login methods aside from ssh, these must be disabled or secured separately.

Installation

Duo Unix with Pluggable Authentication Modules (PAM) support provides a secure and customizable method for protecting Unix and Linux logins. Usually the pam_duo module works best, but if you are unable to use PAM see Duo's login_duo instructions.  The instructions below are cribbed from Duo's pam_duo installation instructions.

Installing pam_duo prerequisites for your system

Install pam_duo

1. Download and extract the latest version of duo_unix (checksum for verification). Change to the extracted directory (note your actual extracted directory name reflects the version downloaded; the example syntax below references version 1.10.1).

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

2. Build and install duo_unix with PAM support ( pam_duo). (For advanced build options, see the README file in the source tarball.)

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

3. Once duo_unix is installed, edit /etc/duo/pam_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;

Public Key Authentication

If you would like to use pam_duo with SSH public key authentication, make the following changes to your sshd_config file (usually in /etc or /etc/ssh).

PubkeyAuthentication yes
PasswordAuthentication no
AuthenticationMethods publickey,keyboard-interactive

Note that you cannot support both password and key authentication on the same SSH service if you are also requiring Duo.  Duo will work with password authentication and it will work with key authentication, but not both forms of authentication on the same service.

PAM Configuration

You'll need to modify your system's PAM configuration to include a line like the following:

auth required pam_duo.so

The location of this line and the specified control flag (e.g. "required", "requisite", "sufficient") varies. For most common configurations, place pam_duo directly after pam_unix (frequently found in common-auth or system-auth on Linux), set pam_unix's control flag to "requisite", and set pam_duo's control flag to whatever pam_unix used to be.

If you want to use pam_duo with your installation of OpenSSH sshd, set both UsePAM and ChallengeResponseAuthentication to yes in your sshd_config file (usually in /etc or /etc/ssh). You should also set UseDNS to no so that PAM Duo is always passed the IP address of the connecting user, rather than the resolved hostname.

UsePAM yes
ChallengeResponseAuthentication yes
UseDNS no

PAM examples

Amazon Linux

/etc/pam.d/system-auth

Before:

auth required pam_env.so
auth sufficient pam_unix.so nullok try_first_pass
auth requisite pam_succeed_if.so uid >= 500 quiet
auth required pam_deny.so

After:

auth required pam_env.so
# auth sufficient pam_unix.so nullok try_first_pass
auth requisite pam_unix.so nullok try_first_pass
auth sufficient pam_duo.so
auth requisite pam_succeed_if.so uid >= 500 quiet
auth required pam_deny.so

SSH Public Key Authentication

/etc/pam.d/sshd

Before:

auth required pam_sepermit.so
auth substack password-auth

After:

auth required pam_sepermit.so
# auth substack password-auth
auth required pam_duo.so

Now when you SSH to this server you should see a duo request:

Duo Push: Send a request to your smartphone. You can use Duo Push if you've installed and activated the free Duo Mobile app on your smart phone or tablet, and your mobile device currently has network connectivity either via WiFi or your cellular data network.

Passcode: Log in using a passcode generated with the Duo Mobile app, or generated by your hardware token.