Google Authenticator

Related articles
OATH
pam_oath
Identity management
Google Authenticator
provides a two-step authentication procedure using one-time passcodes (
OTP
), initially standardized by the
Initiative for Open Authentication (OATH)
. 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
.
Configuration
This section covers configuring the system's
PAM
to require Google Authenticator OTP authentication for SSH and, optionally,
desktop login
.
Note
It is required to generate a
secret key file
for the complete configuration. Consider generating it before editing (and therefore applying) the PAM configuration.
SSH
Warning
If you do all configuration via
SSH
do not close the session before you tested that everything is working, else you may lock yourself out.
Usually one demands two-pass authentication only for remote login. The corresponding PAM configuration file is
/etc/pam.d/sshd
. 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
/etc/pam.d/sshd
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
/etc/pam.d/sshd
:
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.
Warning
Only users that have generated a secret key file (see below) will be allowed to log in using SSH.
To allow login with either the OTP or your Unix password use:
auth
sufficient
pam_google_authenticator.so
Enable keyboard interactive authentication in
/etc/ssh/sshd_config.d/
99-archlinux.conf
:
KbdInteractiveAuthentication yes
Finally,
reload
sshd.service
.
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.
/etc/security/access-local.conf
) 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
/etc/pam.d/sshd
and add the line:
#%PAM-1.0
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
Warning
success=1 only works if at least one other auth line exists after pam_google_authenticator line. If this is not the case, success must be set to done.
Desktop logins
Warning
Do not log out of the session before testing the result on another console.
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
/etc/pam.d/gdm-password
file:
auth required pam_google_authenticator.so
Usage
Every user who wants to use two-pass authentication needs to
generate a secret key file in their home folder, and
setup their OTP generators accordingly
Generating a secret key file
Tip
Install
qrencode
to generate a scannable QR. Scan the QR with the authenticator app to automatically configure the key.
The
google-authenticator
generates a TOTP secret key file as follows:
$ google-authenticator
Do you want authentication tokens to be time-based (y/n) y
generated_QR_code_here
Your new secret key is: ZVZG5UZU4D7MY4DH
Your verification code is 269371
Your emergency scratch codes are:
  70058954
  97277505
  99684896
  56514332
  82717798

Do you want me to update your "/home/
username
/.google_authenticator" file (y/n) y

Do you want to disallow multiple uses of the same authentication
token? This restricts you to one login about every 30s, but it increases
your chances to notice or even prevent man-in-the-middle attacks (y/n) y

By default, tokens are good for 30 seconds and in order to compensate for
possible time-skew between the client and the server, we allow an extra
token before and after the current time. If you experience problems with poor
time synchronization, you can increase the window from its default
size of 1:30min to about 4min. Do you want to do so (y/n) n

If the computer that you are logging into is not hardened against brute-force
login attempts, you can enable rate-limiting for the authentication module.
By default, this limits attackers to no more than 3 login attempts every 30s.
Do you want to enable rate-limiting (y/n) y
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
~/.google_authenticator
, so you can look them up any time as long as you are logged in.
Storage location
If you want to change the secret key files' storage path, you can use the flag
--secret
:
$ google-authenticator --secret="/
path_folder
/
username
"
Then, do not forget to change the location path for PAM, in
/etc/pam.d/sshd
:
/etc/pam.d/sshd
auth required pam_google_authenticator.so user=root secret=/
path_folder
/${USER}
user=root
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:
400
). Here, the owner is root.
$ chown root:root /
path_file
/
secret_key_files
$ chmod 400 /
path_file
/
secret_key_files
Code generation
In the final setup step, each user has to associate the secret key file generated in their home directory with their choice of OTP-generators to serve the authentication codes. A user may set up generators on different devices for redundancy, for example  in an OTP application on a mobile phone and a separate password manager, or decide to rely on the emergency scratch codes generated earlier as backup.
Mobile phone generators
Install a generator application on your mobile phone (e.g.):
FreeOTP
for Android (
F-Droid
,
Google Play
) or iOS (
App Store
).
FreeOTP+
for Android (
F-Droid
,
Google Play
).
Aegis
for Android (
F-Droid
,
Google Play
).
Bitwarden
for Android (
F-Droid
,
Google Play
) or iOS (
App Store
).
Google Authenticator
for Android (
Google Play
) or iOS (
App Store
).
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.
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
gashell
AUR
. An alternative option is
auther-git
AUR
.
KeePassXC
GUI password manager
keepassxc
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
oathtool(1)
. It is available in the
oath-toolkit
package, and can be used as follows:
$ oathtool --totp --base32
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
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
$