[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
github.com 2FA login with oathtool
github.com 2FA login with oathtool
Thu, 21 Sep 2023 09:27:05 -0400
as some may know, github is now requiring 2FA - i do not have a mobile phone
and i use GNU/linux exclusively - as i expected, their docs are not helpful WRT
my use case - someone in the #security IRC channel suggested that oathtool may
work; so i tried it - this was my first time using 2FA or oathtool; so it was
not exactly intuitive - however, i documented the procedure for posterity - the
procedure is probably quite similar for other websites
i dont know if oath-toolkit has a wiki or some other place to put this;
but it may be useful to others - feel free to publish it anywhere -
i offer it under the 'CC0 1.0 Universal' license - no attribution required
== github.com 2FA login with oathtool ==
The initial setup is race against the clock. The entire procedure must be
completed within 30 seconds from when the "Setup authenticator app" page
appears. If you fail, you will need to reload the "Setup authenticator app"
page to get a fresh key, and start over.
First, to save a few precious seconds during the initial setup, and to make the
process more secure and easier in the future, we will be creating two text
files (the file names and locations can be anything you like):
$ mkdir --mode=700 ~/private
$ install -m600 /dev/null ~/private/github-totp
$ install -m600 /dev/null ~/private/github-totp-key
Next, open 'github-totp' with your favorite text editor and add these contents:
oathtool --totp=SHA1 --digits=6 --time-step-size=30s --base32
Note that the '@' character is important; and be sure to type $HOME or the
absolute path to 'github-totp-key'. Tilde expansion '~/' will not work as
Make the 'github-totp' file read-only, executable, and private:
$ chmod 500 ~/private/github-totp
Now, open 'github-totp-key' with your favorite text editor and don your running
Log into Github. If you do not see the "Setup authenticator app" page
immediately, browse to it like so:
* Click on your profile image (top-right), then click "Settings".
* Click "Password and authentication" under the "Access" section of the
* Click "Enable two-factor authentication" under the "Two-factor
Once the "Setup authenticator app" page appears, the clock is ticking. Ready,
On the "Setup authenticator app" page, click the "setup key" link beneath the
qr-code image. Copy the cryptic number/letters shown into the 'github-totp-key'
file and save it. The number/letters should have no spaces and no new-line at
the end. If you type it by hand, not that there are no zero '0' characters. If
you see any, those are the capital letter 'O' characters.
Now, execute the 'github-totp' script.
The command output should be a 6-digit number. Copy that number into the
"Verify the code from the app" text-box on the "Setup authenticator app" page.
With any luck, you did all that quickly enough; and yer good to go. Well,
Next you should see bunches of number/letters on a "Save your recovery codes"
page. At the very least, you will need to click the "I have saved my recovery
codes" button to complete the process. You should probably print those recovery
codes now though, or download them and store them securely/privately on another
computer, CD/DVD, or USB stick.
The next time you login to Github, and forever into the future, you will need a
TOTP (a 6-digit number) for login. Simply execute the 'github-totp' script
again, and use the 6-digit number it generates to log in. Again, you have only
30 seconds to complete the login. Each time the 'github-totp' script is run, it
will produce a different 6-digit number, which expires in 30 seconds. Copy that
number into the Github login page and press the "Sign-in" button.
I suggest trying that now, in a different web browser, without logging out of
your current session, just to make sure it all works. If you logout now and
something went wrong, you may have created a major problem, especially if you
did not save those recovery codes. Please don't blame me or the oath-toolkit
team if things go awry. Blame Github for imposing this extra rigamarole on you.
Lastly, make the 'github-totp-key' file read-only and private:
$ chmod 400 ~/private/github-totp-key
Congratulations. You are safe now. Here a few a few more things you can do for
extra peace of mind.
In full discloser, security nuts will indeed tell you that this is insecure;
because the auth key is stored on the same machine as your web browser.
However, it is no less secure than how I have been logging into Github for the
past 15 years until today, before 2FA was required (and every other website
since forever). Yer a big kid. Decide for yourself.
Optionally, you could encrypt the 'github-totp-key' file now with GPG,
decrypting it on each use in the 'github-totp' script; but this guide will not
explain that. Suffice it to say, if you do so, use a dash '-' character in
place of the '@FILE' in the `oathtool` command, to accept the clear-text key
Optionally, you could keep the 'github-totp' script on a USB stick for decent
level of security, replacing '@$HOME/private/github-totp-key' with the literal
key. Let's call that "1.5FA". In the words of Sir Paul, "Close enough for the
Skiffle!". The 'github-totp-key' file is not strictly needed. I demonstrated
it; because you also may want encrypt that file for an extra decent level of
security. Can never be too safe ya' know.
- github.com 2FA login with oathtool,