Configuring and using 2 factor authentication with Maths ssh gateways

April 2026 update:

This documentation has been revised in the light of changes made to the Maths ssh gateways after external access was initially withdrawn in December 2025 owing to the more stringent cyber-security requirements set by the College. The service has now been reinstated while the original servers in Maths have been replaced by servers in an ICT data centre with all of them now running the latest stable version of Ubuntu Linux (currently 24.04) and use of ssh private/public keypairs containing an embedded passphrase is now mandatory. Connection attempts made with no ssh keypairs, keypairs with mismatched public/private keys and keypairs with no embedded passphrase are rejected and logins using typed-in passwords are no longer supported. These changes are reflected in this updated documentation but setting up and using Google Authenticator on both your computer account and smartphone remains as it was before.

Following the introduction of Google Authenticator 2FA almost 18 months ago, it has proved to be trouble-free and robust, requiring very little user support. The only issue one user encountered was where an Android smartphone had the date & time configured manually instead of using the GSM network date & time protocol and it was nearly 3 minutes fast, so the 2FA authentication kept failing until the phone was reconfigured.

About 2 factor authentication (2FA)

2 factor authentication (2FA) is one of a number of multifactor authentication (MFA) techniques that can be used to add extra protection to network communications by increasing the number of unique user-specific factors that must be verified or matched before access is granted to a service. This is typically used for login connections using ssh but can also be used to protect websites, etc.

The 2FA set-up to be described here uses the popular Google Authenticator smartphone app which is available free of charge for iPhone and Android phones, with versions also available for Windows and Mac systems and as add-ons for some browsers. This app generates a unique verification code, a 6 digit number that updates every 30 seconds, which you use in conjunction with your login account on Maths systems that have been configured to use Google Authenticator 2FA; you will need also to log into the lovelace compute server in Maths initially to complete the set-up procedure that links your phone's app to your Maths login account.

Configuring Google Authenticator for your login account in Maths

First download and install Google Authenticator onto your smartphone from the App Store if you have an iPhone or from the Google Play store if your phone is an Android model.

You will now need to log into lovelace.ma.ic.ac.uk using your College username and password via ssh from one of the following:

• a system on a College campus connected to the wired (Ethernet) network
• a system connected via the Imperial WPA wi-fi network
• a remote system connected to the Colleeg via the Unified Access service

Note that direct external ssh access to lovelace from outside College is now no longer possible as of December 2025 but the alternative routes listed above will still allow you to set up Google Authenticator. Once you have successfully logged in, start the Google Authenticator set-up program to create your 2FA account by typing:

google-authenticator

and the set-up program will start and prompt you if you want the password to be time-limited:

Since you do want TOTP (that is, time-limited) one-time pass codes, answer 'y' to this question and then a large QR code will appear followed by 2 lines of text underneath. Note: on some systems this QR code will not display properly and will instead appear as a broken collection of squares and lines as shown in the example below; this does not signify a problem since the google-authenticator app is optimised to be viewed on an ASCII console terminal typical of servers, which may not be very high resolution nor have the QR encoding libraries installed, and this won't display properly on many desktop system terminal emulators. This broken display also happens with some Macs. However, if you are seeing a broken QR code all is not lost - scroll down...

See? Immediately below the broken QR code is the secret key assigned to this 2FA key, which is actually a more secure way to configure your phone app than using the QR code, which is simply a URL link to the Google Authenticator server. Now open the Google Authenticator app on your phone:

(note: phone screenshots of the main page of the Google Authenticator phone app cannot be made on the phone directly for security reasons so these won't be shown here) so just tap on the '+' button near the bottom right of the app to add a new key and you will see two options: 'Scan a QR code' and 'Enter a setup key'. If the QR code you are seeing on your system is displaying intact, you can simply go ahead and select the scanning option to scan it from your screen your using your phone's camera but if the code is garbled as in the example shown above, you can instead enter the information manually using the 'Enter a setup key' option. This option is described in detail below:

Now, into the Code name box enter a name for this one-time key - the hostname of one of the ssh gateways is an obvious choice (or hostname plus username if you have more than one account on the system) and into the Your key box type your secret key exactly as shown immediately below the mangled QR code (above). Finally, you want a time-based key so leave the last box as it is, set by by default to 'Time based' as shown here:

Tap on the 'Add' button and this key will be saved - you can now return to the previous screen where you will find your new key along with a running countdown timer displaying the current 6 digit code that updates every 30 seconds. Going back to lovelace, you are prompted to test your new key by entering this 6 digit code and all being well, the set-up utility will confirm your 2FA set-up is working properly by displaying the message 'Code confirmed'. (You can skip this step if you want to by typing '-1' but it is strongly advised you do test this as it might save a lot of time later on if things don't work). In addition the set-up utility on lovelace will list your emergency pass codes which you should make a note of - you can use these TOTP codes if your phone is faulty, lost or stolen (these are also stored in your home directory in the file called ~/.google_authenticator).

Finally, the set-up utility concludes with four more questions - answering 'y' to the first one will create the file ~/.google_authenticator and save your settings in it when you finish this set-up session while answering 'y' to the 'disallow multiple uses of the same token' question improves security. For the third question, you are advided to answer 'n' as this enhances security; all modern smartphones and most PCs & laptops have their internal clocks synchronised to an accurate network time source so any differences should be in the sub-second range. The last question should normally be answered with 'y'; the set-up is now complete and the utility exits:

Now you can test it by logging into aachen, cathedral or hessian using a ssh private/public keypair containing an embedded passphrase; if you do not yet have this you can create one as described here since use of this type of ssh keypair is now mandatory on the Maths ssh gateways (up until December 2025, hessian would accept logins from users who typed in their login passwords, with mis-matched keypairs, keypairs lacking a passphrase or even a complete absence of a keypair being ignored but now security has been considerably enhanced and ssh connections require keypairs containing a passphrase which you use instead of the remote system's password, with all other connection attempts now being blocked).

You should see a login dialogue similar to the one shown below, where just after you have typed in your passphrase (remember, passphrase and not password!), you are asked for a 'Verification code' - this is the 6 digit pass code that is currently displayed by the Google Authenticator app on your phone which changes every 30 seconds. Type this in and your login should be accepted: