Scope/Description

• This article covers adding Google Authenticator 2FA to your Houston UI login page on Ubuntu 20.04

Prerequisites

• A working Ubuntu 20.04 server with Houston UI
• Access to the servers terminal

Steps

Installing Google Authenticator PAM Package

• To begin we will need to install the Google Authenticator PAM package. This can be done with the below command:

apt install libpam-google-authenticator

Configuring 2FA

• Once installed we will need to generate a secret key, recovery key, and QR code for our primary user (root). This can be done using the Google-Authenticator wizard by issuing the following command:

If you are using Putty, or another SSH client for this process make sure your terminal window is scaled up otherwise the QR code will be unreadable

google-authenticator

• In the wizard you will want to provide the following answers:

Do you want authentication tokens to be time-based (y/n): y
Do you want me to update your "/root/.google_authenticator" file? (y/n): y 
Do you want to disallow multiple uses of the same authentication token? (y/n): n
This will permit for a time skew of up to 3 minutes between client and server (y/n): n 
Do you want to enable rate-limiting? (y/n): y

• You can now scan the presented QR code with your phone using the Google Authenticator app.

• We will now need to add the google authenticator pam module to our cockpit authentication, this can be done by editing cockpits pam.d file as shown below:

root@ubuntu-45d#:~ nano /etc/pam.d/cockpit

• In this file you will add the below line under the authentication methods:

auth       required     pam_google_authenticator.so secret=/root/.google_authenticator

• Your file should now look like the below image.

• You can now restart the cockpit service.

root@ubuntu-45d:#~ systemctl restart cockpit

Verification

• To verify a successful installation attempt to login to Houston UI. After the username and password prompt you should be shown the below authenticator box.
• Once you provide your verification code you will be allowed into Houston UI.

Troubleshooting

• The most common errors you will run into in this process are “Permission Denied” errors when entering your authenticator key. These are typically caused by Houston not having access to the .google_authenticator file. This can be resolved by setting the file to be chmod 600.
• Another common error is an “Authentication Failed” error. This is typically a result of the .google_authenticator file being created for the wrong user. Houston uses root, so you will need to run the initial google-authenticator command as root.