YubiKey auth for ssh

Posted: 2013-02-03 14:48

The OpenSSH puffer fishA YubiKey Neo

Two-factor authentication buzz has ticked up in the last couple of years, with high-profile site compromises, and promotion by Google. Passwords do not scale; most users have just a few weak passwords they use over and over. The non-savant among us can only remember so many.

Two-factor auth (2FA) is only slightly more inconvenient that the current remember-passwords-for-every-site system, but it significantly reduces the possibility your login can be hacked. Even if the password database of another site you use is compromised, the impact on services supporting 2FA is greatly lessened, because the password alone is not enough to authenicate. You need a second factor, usually a PIN-style code generated by a device, be that a smart phone app, such as Google Authenticator or Authy, or a dedicated hardware device such as an RSA SecurID, or OATH token, from someone like Gemalto

The prohibitive expense of such systems has been a barrier to widespread use, but open standards for tokens have allowed cheaper entrants into the market. Gemalto is one of many OATH token makers; YubiKey is another.

In this brief howto, I'll explain how to configure YubiKey two-factor authentication for ssh login. The second factor credential is authenticated against Yubico's YubiCloud auth service. The other factor is your local account password.

This howto is written for Ubuntu 12.04 LTS. You can make this work on other distributions, but keep in mind that literally following these instructions on another distribution will likely not work; you'll need to use your brane a bit, but there shouldn't be huge differences in the process.

Things you'll need to have:

  • a YubiKey! Buy one at the Yubico store

    They're not expensive; you only need the most basic one for this to work.

  • your YubiKey id.

    This is the first twelve characters emitted by your YubiKey when it's triggered. If you're using bash, issuing this command may be easier than counting to twelve:

    read -p "Enter a YubiKey OTP: " s && echo 'The key id is' ${s:0:12}

    Trigger your YubiKey when prompted, and your YubiKey's unique id will be extracted and displayed.

  • your Yubico id & API key from yubico.

    You generate your Yubico id & API key at Yubico's key retrieval page.

    Login to your Yubico account, which you created when you purchased your key. You will need to enter the email address you used when you bought the key, and a one time password generated by one of your keys.

    Make a note of the numeric client id & the long, ugly string which is the Secret key.

    Keep these secure.

With this information in hand, you are ready to configure your server's authentication.

  • install libpam-yubico

    apt-get install libpam-yubico

  • edit /etc/yubikey_mappings

    This file maps your Linux userid to the YubiKey id which is allowed to authenticate login.

    Lines in yubikey_mappings have the following format:


    You can associate any number of YubiKeys with a single account.

    In my case, my yubikey id is ccccclpxlnzq, and the account I want to authenticate with this key is carl. My yubikey_mappings file looks like this:

  • Modify the configuration for sshd in /etc/pam.d/sshd

    Because we need to make changes to the parameters for pam_unix.so, we will need to comment the line:

    @include common-auth

    and move the pam_unix.so configuration into the sshd auth config file. Add these lines:

# Yubikey 2FA, pulling in Unix auth from common-auth, because we have to modify
# the pam_unix.so parms to add 'use_first_pass'

auth      requisite pam_yubico.so id=90736 key="AgIrWevHerogikhoapHaiWeykWy"  authfile=/etc/yubikey_mappings debug
auth [success=1 default=ignore]    pam_unix.so use_first_pass nullok_secure
auth requisite           pam_deny.so
auth required            pam_permit.so

Here id is the auth id and key is the API key from the key retrieval page at Yubico. The only change to the standard pam_unix.so auth lines is the addition of use_first_pass.

Once you save this change, Yubikey 2FA should be in effect for all users listed in /etc/yubikey_mappings.

Your login process will still involve your Unix password, but instead of pressing return once you type your password, activate your Yubikey. The combined unix password and the YubiKey OTP will be passed to the pam_yubico module. pam_yubico.so will split your unix password from your Yubikey OTP, and verify the Yubikey password with the YubiCloud servers. If the YubiCloud servers indicate the OTP is valid, the unix password portion will be passed along to pam_unix.so, courtesy of the use_first_pass option. pam_unix.so will verify the password against the system's password database. If the password is a match, access will be granted.

    Contents © 2013 Jason Boyles - Powered by Nikola