Google Authenticator

Google Authenticator provides a two-step authentication procedure using one-time passcodes (OTP). The OTP generator application is available for iOS, Android and Blackberry. The authentication mechanism integrates into the Linux PAM system. This guide shows the installation and configuration of this mechanism.

For the reverse operation (generating codes compatible with Google Authenticator under Linux) see #Code generation below.

Installation

Install the libpam-google-authenticator package, which provides the client program google-authenticator(1) and the PAM module pam_google_authenticator.so. The development version is available with google-authenticator-libpam-git^AUR.

Setting up PAM

Usually one demands two-pass authentication only for remote login. The corresponding PAM configuration file is . In case you want to use Google Authenticator globally you would need to change /etc/pam.d/system-auth, however, in this case proceed with extreme caution to not lock yourself out. In this guide we proceed with editing which is most safely (but not necessarily) done in a local session.

To enter both, your unix password and your OTP, add pam_google_authenticator.so above the system-remote-login lines to :

auth            required        pam_google_authenticator.so
auth            include         system-remote-login
account         include         system-remote-login
password        include         system-remote-login
session         include         system-remote-login

This will ask for the OTP before prompting for your Unix password. Changing the order of the two modules will reverse this order.

To allow login with either the OTP or your Unix password use:

auth            sufficient      pam_google_authenticator.so

Enable keyboard interactive authentication in :

KbdInteractiveAuthentication yes

Finally, reload .

Warning: OpenSSH will ignore all of this if you are authenticating with a SSH-key pair and have disabled password logins. However, as of OpenSSH 6.2, you can add AuthenticationMethods to allow both: two-factor and key-based authentication. See OpenSSH#Two-factor authentication and public keys.

Request OTP only when connecting from outside your local network

Sometimes, we just want to enable the 2FA capability just when we connect from outside our local network. To achieve this, create a file (e.g. ) and add the networks where you want to be able to bypass the 2FA from:

# only allow from local IP range
+ : ALL : 192.168.20.0/24
# Additional network: VPN tunnel ip range (in case you have one)
+ : ALL : 10.8.0.0/24
+ : ALL : LOCAL
- : ALL : ALL

Then edit your and add the line:

#%PAM-1.0
#auth     required  pam_securetty.so     #disable remote root
auth [success=1 default=ignore] pam_access.so accessfile=/etc/security/access-local.conf
auth      required  pam_google_authenticator.so
auth      include   system-remote-login
account   include   system-remote-login
password  include   system-remote-login
session   include   system-remote-login

Generating a secret key file

Every user who wants to use two-pass authentication needs to generate a secret key file in their home folder. This can very easily be done using google-authenticator:

It is recommended to store the emergency scratch codes safely (print them out and keep them in a safe location) as they are your only way to log in (via SSH) when you lost your mobile phone (i.e. your OTP-generator). They are also stored in , so you can look them up any time as long as you are logged in.

Setting up your OTP-generator

Install a generator application on your mobile phone (e.g.):

FreeOTP for Android[F-Droid], [Google Play]/iOS (no releases since 2016).
FreeOTP+ for Android[F-Droid].
Aegis for Android[F-Droid], [Google Play].
andOTP for Android[F-Droid], [Google Play].
Google Authenticator for Android/iOS.

In the mobile application, create a new account and either scan the QR code from the URL you were told when generating the secret key file, or enter the secret key (in the example above 'ZVZG5UZU4D7MY4DH') manually.

Now you should see a new passcode token being generated every 30 seconds on your phone.

Testing

SSH to your host from another machine and/or from another terminal window:

$ ssh hostname
login as: username
Verification code: generated/backup_code
Password: password
$

Storage location

If you want to change the secret key files' storage path, you can use the flag :

$ google-authenticator --secret="/PATH_FOLDER/USERNAME"

Then, do not forget to change the location path for PAM, in /etc/pam.d/sshd:

is used to force PAM to search the file using root user.

Also, take care with the permissions of the secret key file. Indeed, the file must be only-readable by the owner (chmod: ). Here, the owner is root.

$ chown root.root /PATH_FILE/SECRET_KEY_FILES
  chmod 400 /PATH_FILE/SECRET_KEY_FILES

Desktop logins

The Google Authenticator PAM plugin can also be used for console logins and with GDM. Just add the following to /etc/pam.d/login or the file:

auth required pam_google_authenticator.so

Code generation

If you have Google Authenticator configured with other systems, then losing your device can prevent you from being able to log in to those systems. Having additional ways to generate the codes can be helpful.

Code managers

A script that enables the display, generation, storage and management of Google Authenticator codes is provided by . An alternative option is .

KeePassXC

GUI password manager allows associating Google Authenticator codes to its entries, and then it can generate OTP codes and export its keys via QR code.

Command line

The easiest way to generate codes is with . It is available in the package, and can be used as follows:

$ oathtool --totp -b secret_key

On most Android systems with sufficient user access, the Google Authenticator database can be copied off the device and accessed directly, as it is an sqlite3 database. However, at some point in July 2022, the secret column on the accounts table started using encryption. If your database backup does not use this encryption, this shell script will read a Google Authenticator database and generate live codes for each key found:

google-authenticator.sh

#!/bin/sh

# This is the path to the Google Authenticator app file.  It is typically
# located in /data under Android.  Copy it to your PC in a safe location and
# specify the path to it here.
DB="/path/to/com.google.android.apps.authenticator/databases/databases"

sqlite3 "$DB" 'SELECT email,secret FROM accounts;' | while read A
do
        NAME=`echo "$A" | cut -d '|' -f 1`
        KEY=`echo "$A" | cut -d '|' -f 2`
        CODE=`oathtool --totp -b "$KEY"`
        echo -e "\e[1;32m$CODE\e[0m - \e[1;33m$NAME\e[0m"
done

gollark: OIR™ has one.

gollark: How did it do *that*?

gollark: ++remind 2h fix

gollark: ++magic reload_ext irc_link

gollark: How does it keep *doing* that?

This article is issued from Archlinux. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.