How to use Google Authenticator in Debian Wheezy

Google have [released a PAM for the Google
Authenticator](http://code.google.com/p/google-authenticator/source/browse/#hg%2Flibpam)
which can use used together with its mobile app to provide two-step
authentication for linux-based systems.

Note that this uses the same mobile app as for [2-step
verification](http://www.google.com/support/accounts/bin/static.py?page=guide.cs&guide=1056283&topic=1056284)
which you may already use for GMail and other Google Apps.

This document describes how to set up two-step authentication using
the Google Authenticator PAM on a Debian Wheezy system.  It should be
possible to modify these instructions for other linux variants and
older versions of Debian linux but Wheezy is convenient since there is
already a `libpam-google-authenticator` package.


## Installation on the phone

If you are using Android, install the [Google Authenticator App from
the
Market](https://market.android.com/details?id=com.google.android.apps.authenticator).

Google Authenticator is available for other platforms too.  It's
currently available for iOS and Blackberry.  See the
[google-authenticator](http://code.google.com/p/google-authenticator/)
project page for apps for other mobile platforms.


## Installation on the server

Tip: before you start tinkering with pam settings for ssh, make sure
you have an alternative way into your system, such as a serial console
or a keyboard+monitor.  I.e. if your machine is in some remote
colocation facility and all you have is ssh access, you should be
pretty confident you know what you are doing.

Install the Google Authenticator package

    sudo apt-get install libpam-google-authenticator

Generate a key and the emergency login codes. (Each user needs to do
this and after you have enabled the PAM, those users who have not
generated a key will not be able to log in any more.)

    google-authenticator

This will print a QR code in your ANSI terminal.  Scan this QR code
using the mobile app to send the secret to the App on your phone.

It will also list six emergency login codes which can be used in case
you do not have your phone available.  Keep a hard copy of these codes
in a safe place such as your wallet.

Create a `/etc/security/access-local.conf` to allow connections from
subnet 192.168.1.0 (edit to suit) to skip the two-step code:

    LOCAL_SUBNET="192.168.1.0/24"
    cat <<EOF | sudo tee /etc/security/access-local.conf
    # only allow from local IP range
    + : ALL : LOCAL
    + : ALL : ${LOCAL_SUBNET}
    - : ALL : ALL
    EOF

Edit `/etc/pam.d/ssh` by appending two `auth` lines to the end of the
file:

    cat <<EOF | sudo tee -a /etc/pam.d/ssh
    # skip one-time password if logging in from the local network
    auth [success=1 default=ignore] pam_access.so accessfile=/etc/security/access-local.conf
    auth required pam_google_authenticator.so
    EOF

If you want two-step authentication for _all_ ssh connections no
matter the source IP address, you only need the last `auth` line from
above (and you can skip creating the `/etc/security/local-access.conf`
file).

Finally, make sure in `/etc/ssh/sshd_config` the following is enabled

    ChallengeResponseAuthentication yes

This was `no` on my freshly installed Wheezy system.


## Further information

   * [Google Authenticator project page on Google
     Code](http://code.google.com/p/google-authenticator/)
   * [PAM Installation
     Instructions](http://code.google.com/p/google-authenticator/wiki/PamModuleInstructions)