For some time now GitHub have started requiring account owners to use two factor authentication (2FA) when signing in to the GitHub web site using a browser.
A few weeks ago I received notification from GitHub that I should enable two factor authintication (2FA) for my account. This meant that, in addition to the usual username/password, I will also need a second method of authentication.
The GitHub help page on Configuring two-factor authentication provides various options for configuring the second source of the 2FA authentication. These include installing an app on my phone, use the SMS on my mobile phone, or use a third party authenticator.
I was not keen on installing yet another mobile app on my phone, or rely on the SMS service. While the SMS option works fine most of the time, it does not work if there are roaming issues when away from home! GitHub does not offer the option of email as the second authentication method, which is often offered by others as an alternative for, or in addition to, SMS based authentication.
However, since my first preference in such situations is always a CLI based solution, I searched further and eventually came across the OATH Toolkit, which provides exactly what GitHub requires - Time-based One Time Password (TOTP).
The CLI based solution
The OATH Toolkit can be obtained from the
Download page. It
is also available as a package on various Linux distros. Once
installed, you will have the main command available to you –
When enabling the 2FA, the GitHub page will display a QR code that you
are expected to scan using your mobile app. As an alternative to the
QR code, there is also a
setup key link near the QR code that will
show a 16 character code. This is a base-32 representation of the
secret information needed for the generation of the TOTP specific to
your GitHub account. Copy the code and keep it in a very safe place!
When asked by GitHub, use the following command to generate the TOTP:
oathtool -b --totp KEY
This will print a 6 digit number, e.g.
123456, that should be typed
in the entry box.
BEWARE: If you are running the above command on a shared host, the
KEY will be momentarily visible to others. To be safe, you can ask
oathtool to read the
KEY from the standard input:
oathtool -b --totp -
You will also be asked to download and save the recovery codes, copy these codes and keep them in a safe and secure place! Once you confirm that you have saved the recovery codes, your account will have 2FA enabled.
From now on in addition to the username/password you will also be
asked for the 2FA key, which you can generate using the
For those using the pass command to manage their passwords, there is a companion extension command (pass-otp) that will enable you to keep the GitHub secret key (the 16 character key) in the password store along with your other passwords.
To start using
pass-otp, add your GitHub
secret key to the
pass otp insert -s --issuer GitHub
Enter secret for this token:
This will create a password-store entry and print the PASSWORD-NAME.
To obtain the TOTP during sign-in, use:
pass otp PASSWORD-NAME
and type, or copy-paste, the 6 digit number in the entry box on the GitHub web page.
Or, to have it copied to the clipboard for you, use:
pass otp -c PASSWORD-NAME
Copied OTP code for PASSWORD-NAME to clipboard. Will clear in 45 seconds.
Now, it’s just a matter of pasting the code in the browser entry box.
To read further
In addition to the descriptions on the GitHub help page on Configuring two-factor authentication, you can learn further about the OATH and TOTP from the section under External Resources and Applications on the OATH Toolkit web site. It lists the relevant RFCs describing OATH and TOTP.
I have described above the minimal steps needed to enable 2FA for my own use. This should probably be sufficient for most use cases.
This solution works for me because I access my GitHub account via the browser on my laptop/PC, and never on a phone or tablet. It has worked fine so far :-)