Intro

As part of the rebuild on my Plex Media Server using CentOS 7, I had intended to configure Google Authenticator but hadn’t gotten around to doing it yet.  As I got into the process recently I discovered that many of the steps that I had used when configuring my CentOS 6 Digital Ocean droplet were out of date to the point of uselessness.

I also discovered that most of the guides that I found either relied on the older 1.0 code release which was also outdated or used a unknown RPM repo.  As such I decided to write up the process that I followed to use the code downloaded from the official GitHub repository.

NOTE: If you are doing this in an enterprise setting, it is likely that your company has particular settings and restrictions that you may need to adhere to (e.g., not running things as the root user). Also, please note that all of my examples use the CentOS defaults unless specifically noted.

Install the pre-requisites

As I have started with a minimal CentOS 7 install (since I don’t have any need for a GUI or the other extras) many of the packages I needed were not part of the baseline install set.  Here is the list of additional packages that I installed (note that this will get quite a few items to satisfy numerous dependencies)

• autoconf
• automake
• bind-utils
• gcc
• libtool
• make
• nmap-netcat
• ntp
• pam-devel
• unzip
• wget

[code language=”bash”]
[root@server ~]# yum -y install autoconf automake bind-utils gcc libtool make nmap-netcat ntp pam-devel unzip wget
[/code]

 

 

Configure and test NTP

An essential part of the 2FA system is an accurate clock.  This is because at it’s heart the Google Authenticator system is a Time-based One-time Password Algorithm (TOTP).  If you have too much skew between the clock on the server and the clock on the client, then your codes will fail intermittently.

Test NTP pool DNS resolution

First you need make sure that the name used by the NTP configuration file for the server will resolve to an IP address.

CentOS 7 uses the following as the NTP server pool set:

• 0.centos.pool.ntp.org
• 1.centos.pool.ntp.org
• 2.centos.pool.ntp.org
• 3.centos.pool.ntp.org

Test Network connectivity

Next up you should test that you actually have baseline connectivity to the NTP endpoint.  In general this should just work, like the DNS resolution did, however if you are running your server behind an IPS or a network firewall, it is possible that you will need to explicitly allow outbound NTP connections over port 53/UDP.

Please note that in the following code snippet, a result of zero (0) indicates a successful connection, whereas a result of one (1) indicates a failure to connect to the endpoint.

[code language=”bash”]
[root@server ~]# echo | nc -u -w1 0.centos.pool.ntp.org 53 >/dev/null 2>&1 ;echo $?
0
[/code]

Test basic NTP functionality

Now that you have tested (and resolved any issues you found) your DNS resolution and baseline connectivity to the NTP endpoint you need to perform an actual application layer test.

[code language=”bash”]
[root@server ~]# ntpdate -q 0.centos.pool.ntp.org
server 208.75.88.4, stratum 2, offset -0.006191, delay 0.10498
server 184.105.182.7, stratum 2, offset -0.001065, delay 0.11761
server 52.0.56.137, stratum 3, offset -0.005018, delay 0.06509
server 142.54.181.202, stratum 2, offset -0.000588, delay 0.09003
28 Aug 17:07:05 ntpdate[16085]: adjust time server 142.54.181.202 offset -0.000588 sec
[/code]

Configure NTP daemon for startup

If you get a complete test, the next step will be to configure the NTP daemon to startup at system boot and to start the service.

Build and Install Google Authenticator

Download the codebase

As I stated in the intro, many of the guides used an outdated codebase from the now defunct Google Code Project Hosting service or they used an RPM repository that I didn’t find completely trustworthy.  To resolve those problems, I decided to just rely on the GitHub repository that is maintained by the Google developer team.

The first step is to download the code.  The GitHub repository for the PAM module is located at https://github.com/google/google-authenticator/tree/master/libpam.

[code language=”bash”]
[root@server ~]# cd /opt
[root@server opt]# wget -q https://github.com/google/google-authenticator/archive/master.zip
[/code]

Compile and install

NOTE: as part of the build and install process, I have included a directive to change the base directory that is used for the installation.  The reason for this is due to the need to create two symbolic links.  This will be covered in the next section.

The following are the steps as laid out in the PAM Module Instructions from the wiki: https://github.com/google/google-authenticator/wiki/PAM-Module-Instructions

./bootstrap.sh
./configure
make
make install

To anyone that has compiled from source, these are likely to be sufficient, however I have included an abbreviated version of my code snippet for this since it may provide additional information for those that aren’t quite so familiar with the process.

Configure PAM and SSH

The next two subsections cover the creation of two symbolic links (mentioned in the note in the previous section) and the change to the configuration file for the PAM system governing the SSH daemon.  Additionally, there are a couple of modifications that you might need to perform on the SSH daemon configuration as well, depending on your setup.

Add symlinks to 64bit libraries and module

During my installation, I ran into a situation that was caused by the location used for the installation of the PAM library and object files.  I solved this in two steps:

1. Change the base location of the file installation
2. Addition of two symbolic links

The first step was covered in the build process by the addition of a parameter to the call to the configure script:

[code language=”bash”]
[root@server libpam]# ./configure –prefix=/usr
[/code]

The second step was accomplished using the following commands:

[code language=”bash”]
[root@server ~]# cd /usr/lib64/security/
[root@server security]# ln -s /usr/lib/security/pam_google_authenticator.so pam_google_authenticator.so
[root@server security]# ln -s /usr/lib/security/pam_google_authenticator.la pam_google_authenticator.la
[/code]

As you can see from the following directory listing, this results in two symbolic links pointing back to the installed files in /usr/lib/security.

[code language=”bash”]
[root@server security]# pwd
/usr/lib64/security
[root@server security]# ls -l `find . -maxdepth 1 -type l -print`
lrwxrwxrwx 1 root root 45 Aug 28 17:58 ./pam_google_authenticator.la -> /usr/lib/security/pam_google_authenticator.la
lrwxrwxrwx 1 root root 45 Aug 28 17:58 ./pam_google_authenticator.so -> /usr/lib/security/pam_google_authenticator.so
lrwxrwxrwx. 1 root root 15 Jan 17 2016 ./pam_selinux_permit.so -> pam_sepermit.so
lrwxrwxrwx. 1 root root 11 Jan 17 2016 ./pam_unix_acct.so -> pam_unix.so
lrwxrwxrwx. 1 root root 11 Jan 17 2016 ./pam_unix_auth.so -> pam_unix.so
lrwxrwxrwx. 1 root root 11 Jan 17 2016 ./pam_unix_passwd.so -> pam_unix.so
lrwxrwxrwx. 1 root root 11 Jan 17 2016 ./pam_unix_session.so -> pam_unix.so
[/code]

Update PAM config file for SSH

After you have the files installed in the correct locations, you need to update the PAM configuration for SSH.  Now, there are a number of ways that you can go about doing this.  I chose to use an inline edit with sed.

NOTE: editing PAM configurations can result in denying access to your system if performed incorrectly.  When editing the SSH PAM configuration file, always do the following:

1. BACKUP the original file
2. Make sure you have console access
3. Open a secondary SSH terminal so that if you screw up you are still logged in

[code language=”bash”]
[root@server ~]# cd /etc/pam.d/
[root@server pam.d]# cp -p sshd sshd_backup
[root@server pam.d]# sed -i “2iauth required pam_google_authenticator.so” sshd
[/code]

If you would like to use HOTP (counter based) instead of TOTP add the following the end of the text to be inserted using the sed command in the above command example:

no_increment_hotp

Update the SSH configuration

In order to make the SSH part work there are three configuration settings that have to be set in a particular way:

• PasswordAuthentication
• UsePAM
• ChallengeResponseAuthentication

The configuration file is located here:

/etc/ssh/sshd_config

The desired settings for these are as follows:

PasswordAuthentication yes
UsePAM yes
ChallengeResponseAuthentication yes

The first two are likely already set to be to the desired value, but the third one will need to be changed from “no” to “yes” on a default CentOS 7 install.  To check your settings run the following command and the edit the configuration file if needed:

[code language=”bash”]
[root@server ~]# egrep “PasswordAuthentication|UsePAM|ChallengeResponseAuthentication” /etc/ssh/sshd_config | egrep -v “#”
PasswordAuthentication yes
ChallengeResponseAuthentication yes
UsePAM yes
[/code]

Next you need to restart the SSH daemon so that the changes take effect.  Warning: until you have configured the userland piece (see the next section) your SSH users won’t be able to login. (This includes the root user, but you aren’t logging in remotely as root anyway right?)

Configure userland

This step involves configuring the users to use a TOTP token by running the google-authenticator binary and then answering some questions.  Here is the usage statement for the binary:

google-authenticator [<options>]
 -h, --help Print this message
 -c, --counter-based Set up counter-based (HOTP) verification
 -t, --time-based Set up time-based (TOTP) verification
 -d, --disallow-reuse Disallow reuse of previously used TOTP tokens
 -D, --allow-reuse Allow reuse of previously used TOTP tokens
 -f, --force Write file without first confirming with user
 -l, --label=<label> Override the default label in "otpauth://" URL
 -i, --issuer=<issuer> Override the default issuer in "otpauth://" URL
 -q, --quiet Quiet mode
 -Q, --qr-mode={NONE,ANSI,UTF8}
 -r, --rate-limit=N Limit logins to N per every M seconds
 -R, --rate-time=M Limit logins to N per every M seconds
 -u, --no-rate-limit Disable rate-limiting
 -s, --secret=<file> Specify a non-standard file location
 -S, --step-size=S Set interval between token refreshes
 -w, --window-size=W Set window of concurrently valid codes
 -W, --minimal-window Disable window of concurrently valid codes

The following snippet shows the command output and answers of run of the google-authenticator binary for a regular user (NOTE: I have removed the actual emergency codes and the secret key, also if your terminal will display it, you may be presented with a QR code to scan.):

[code language=”bash”]
[root@server ~]# su – johndoe
[johndoe@server ~]$ google-authenticator

Do you want authentication tokens to be time-based (y/n) y
Your new secret key is: SECRET_KEY_HERE
Your verification code is VERIFY_CODE_HERE
Your emergency scratch codes are:
EMER_CODE_HERE
EMER_CODE_HERE
EMER_CODE_HERE
EMER_CODE_HERE
EMER_CODE_HERE

Do you want me to update your “/home/johndoe/.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. 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 +-1min (window size of 3) to about +-4min (window size of
17 acceptable tokens).
Do you want to do so? (y/n) y

If the computer that you are logging into isn’t 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
[/code]

If you would like to just provide a single command for your users to run to avoid having to tell them the answers as laid out in the above example, use the following:

google-authenticator --time-based --disallow-reuse --window-size=17 --rate-limit=3 --rate-time=30 --force

Extra bits

The following sections detail two useful options.

Whitelist a network

It is possible that you may have a particular network segment, that by it’s very nature is secure enough to not require the additional steps of 2FA.  If this is the case for your installation, here is how you can whitelist a network segment.

1. Create access control list
2. Update /etc/pam.d/sshd to use to ACL

The following shows the contents of an ACL that would whitelist the network 192.168.1.0/24

[code language=”bash”]
[root@server ~]# vi /etc/security/2fa-acl.conf
[root@server ~]# cat /etc/security/2fa-acl.conf
# Allows certain network segments to skip 2FA
+ : ALL : 192.168.1.0/24
+ : ALL : LOCAL
– : ALL : ALL
[/code]

Once you have the ACL built add an exclusionary conditional to the SSH PAM configuration file BEFORE the line that was added to activate the pam_google_authenticator.so module.  For example:

[code language=”bash”]
[root@server ~]# sed -i “2iauth [success=1 default=ignore] pam_access.so accessfile=/etc/security/2fa-acl.conf” /etc/pam.d/sshd
[/code]

Allow unconfigured users

If you have a single user or two it will be easy enough to manage providing the string activate the google-authenticator system for a user, but if you are managing a server with a large number of users, you might want to establish a grace period during which users that have not yet configured their local account to continue to login.

This can be accomplished by adding this parameter to the end of the PAM configuration file line:

nullok

If you have already added the line and you just want to easily add the new parameter, then use the following sed command:

[code language=”bash”]
[root@server ~]# sed -i ‘2s/$/ nullok/’ /etc/pam.d/sshd
[/code]

Troubleshooting

If you encounter login failures during your testing, a good place to start is the content of the following log files:

• /var/log/secure
• /var/log/audit/audit.log