Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Tutorial for two factor authentication #528
Conversation
webteam-app
commented
Dec 4, 2017
|
User is not a collaborator of this repo. Please start demo manually. |
anthonydillon
added
the
Tutorials Content
label
Dec 5, 2017
m4sk1n
changed the title from
[WIP] Tutorial for two factor authentication
to
Tutorial for two factor authentication
Dec 5, 2017
caldav
self-assigned this
Dec 7, 2017
caldav
requested changes
Dec 7, 2017
Very useful and pragmatic, good job!
I've commented on some things that needs fixing.
Two other things:
- It's not clear that these steps should be applied server side and not client side.
- You may want to fudge or alter the QR code a bit, and do so visibly, so people notice it's as sensitive as the secret key you blurred.
Thank you for this!
| @@ -0,0 +1,129 @@ | ||
| +--- | ||
| +id: configure-ssh-2fa | ||
| +summary: Configure SSH to use two factor authentication |
caldav
Dec 7, 2017
Contributor
"two factor" -> "two-factor" (the same comment is to be applied to the rest of the tutorial, I won't point it out each time)
| +categories: server | ||
| +tags: tutorial,ssh,security,ubuntu,terminal | ||
| +difficulty: 2 | ||
| +status: Published |
| +status: Published | ||
| +published: 2017-12-04 | ||
| +author: Marcin Mikołajczak <me@m4sk.in> | ||
| + |
caldav
Dec 7, 2017
Contributor
Please add feedback_url: https://github.com/canonical-websites/tutorials.ubuntu.com/issues to the metadata
| + | ||
| +## Overview | ||
| + | ||
| +SSH, the secure shell, is often used to access remote Linux systems. Because we often use it to connect with computer containing important data, it's recommended to add another security layer. Here comes the two factor authentication (*2FA*). |
| +All you need is a PC running Ubuntu and configured SSH connection. | ||
| + | ||
| + - You should understand the danger of stolen passwords. | ||
| + - You don't need to know what two factor authentication is and how it works. |
caldav
Dec 7, 2017
Contributor
Let's be a bit more pragmatic:
What you'll need
- A computer running Ubuntu 16.04 LTS or above
- A phone running Android or iOS
- A configured SSH connection
| + - You don't need to know what two factor authentication is and how it works. | ||
| + | ||
| + | ||
| +## What is two factor authentication |
caldav
Dec 7, 2017
Contributor
I'm suggesting you move this section in the middle of the first page so it would look like this:
PAGE1 - Overview
[purpose of the tutorial]
What is two-factor authentication
[context about the topic]
What you'll need
- ...
- ...
PAGE 2 - Installing and configuring required packages
| +## What is two factor authentication | ||
| +Duration: 1:00 | ||
| + | ||
| +Multi factor authentication is a method of confirming your identity using at least two different was of authentication. The most common and easiest to implement example of two factor authentication uses combination of **passphrase** (often called *password*, which implies that you should just use single word to log in) and one-time-passcode generated by special mobile app. |
caldav
Dec 7, 2017
Contributor
Multi-factor
ways
uses a combination
"(often called password, which implies that you should just use single word to log in)" is a nice touch, but confuses the point of the paragraph. Maybe simplify it with: "(a complex password, often made of several words)"
"one-time passcode"
by a special mobile app
Also, please put "one-time passcode" in bold too, because it helps putting the two auth factors on a same level.
| + | ||
| +Multi factor authentication is a method of confirming your identity using at least two different was of authentication. The most common and easiest to implement example of two factor authentication uses combination of **passphrase** (often called *password*, which implies that you should just use single word to log in) and one-time-passcode generated by special mobile app. | ||
| + | ||
| +We will use Google Authenticator app available for Android (in [Play Store]) and iOS (in [iTunes]) to generate authentication codes. |
caldav
Dec 7, 2017
Contributor
"We will use the Google Authenticator app available for Android (in the [Play Store]) and iOS (in [iTunes]) to generate authentication codes."
Maybe one more sentence: "If you are using another phone OS or authentication device, you can follow and adapt this tutorial, as the basic principles of 2FA still apply".
| +## Installing and configuring required packages | ||
| +Duration: 3:00 | ||
| + | ||
| +### Installing required package |
caldav
Dec 7, 2017
Contributor
To avoid a repetition with the title just above, maybe something a bit more descriptive, such as "Installing the Google Authenticator PAM module"
| +Start a terminal session and type: | ||
| + | ||
| +```bash | ||
| +$ sudo apt install libpam-google-authenticator |
| + | ||
| +### Configuring SSH | ||
| + | ||
| +To make SSH using the oath PAM module, add following to the /etc/pam.d/sshd file: |
caldav
Dec 7, 2017
Contributor
"To make SSH use"
"the following line at the end of the /etc/pam.d/sshd file"
| +auth required pam_google_authenticator.so | ||
| +``` | ||
| + | ||
| +Now you need to restart `sshd` daemon using: |
| +Now you need to restart `sshd` daemon using: | ||
| + | ||
| +```bash | ||
| +$ sudo systemctl restart sshd.service |
| +$ sudo systemctl restart sshd.service | ||
| +``` | ||
| + | ||
| +Modify `/etc/ssh/sshd_config` – change `ChallengeResponseAuthentication` from `no` to `yes`: |
caldav
Dec 7, 2017
Contributor
"...from no to yes, so this part of the file looks like this:
[...]
# Change to yes to enable challenge-response passwords (beware issues with
# some PAM modules and threads)
ChallengeResponseAuthentication yes
[...]
| +## Configuring authentication | ||
| +Duration: 2:00 | ||
| + | ||
| +Google Authenticator makes configuration of two factor authentication much easier, comparing to (for example) libpam-oath. |
| + | ||
| +Google Authenticator makes configuration of two factor authentication much easier, comparing to (for example) libpam-oath. | ||
| + | ||
| +Use `google-authenticator` command. It will ask you a few questions. I recommend to make tokens time-based, update `.google_authenticator` file, disallow multiple uses, the next one depends of you (I increased it, but most people won't need it) and enable rate-limiting. |
caldav
Dec 7, 2017
Contributor
You are going a bit too fast here. If you don't want to go into the details of explaining the purpose of each step, maybe you could use bullet points, here is a suggestion:
"In a terminal, run the google-authenticator command.
It will ask you a series of questions, here is a recommended configuration:
- Make tokens "time-based": yes
- Update the
.google_authenticatorfile: yes - Disallow multiple uses: yes
- Increase the original generation time limit: no
- Enable rate-imiting: yes
You may have noticed the giant QR code that appeared during the process, underneath are your emergency scratch codes to be used if you don't have access to your phone: write them down on paper and keep them in a safe place."
| + | ||
| +Write down your emergency codes on paper or find other, safe place to keep them. You will need it if you won't have access to your phone. | ||
| + | ||
| +That's all. Now, let's open Google Authenticator and add our secret code to make it work. |
caldav
Dec 7, 2017
Contributor
secret code -> secret key (to match the terminology the user sees in the terminal output)
| + | ||
| + | ||
| +negative | ||
| +: We shouldn't use unencrypted services to store secret key, so don't place it in your notes synchronization service and so on. If you don't want to type the key manually, use QR code. |
caldav
Dec 7, 2017
Contributor
We shouldn't -> Don't
secret key -> secret keys
", such as a notes synchronization service and so on."
"use the QR code."
| +negative | ||
| +: We shouldn't use unencrypted services to store secret key, so don't place it in your notes synchronization service and so on. If you don't want to type the key manually, use QR code. | ||
| + | ||
| +## Adding secret to Google Authenticator |
| +## Adding secret to Google Authenticator | ||
| +Duration: 2:00 | ||
| + | ||
| +We will use latest version of Authenticator from Play Store. The progress shouldn't look very different on iOS. |
| + | ||
| + | ||
| + | ||
| +### Add secret through QR code |
| + | ||
| +### Add secret through QR code | ||
| + | ||
| +Touch the Add icon (+) and select “Scan a barcode”. Use phone camera to scan QR code. You can use this key to access SSH. |
caldav
Dec 7, 2017
Contributor
the phone camera
"the QR code displayed in your terminal output"
"You can use this key to access SSH" <- Maybe keep this sentence for later, as it applies to both methods, no?
| + | ||
| + | ||
| + | ||
| +### Add secret through key |
| + | ||
| +### Add secret through key | ||
| + | ||
| +Touch the Add icon (+) and select “Enter a provided key”. Enter the name that will make you remember it's authentication key for your SSH shell. Type key provided by `google-authenticator` command. |
caldav
Dec 7, 2017
Contributor
"... Enter a name that you will recognise as being your 2FA method for SSH, then type the secret key provided..."
| +## Getting help | ||
| +Duration: 1:00 | ||
| + | ||
| +Congratulations! You have just configured two factor authentication for SSH shell using Google Authenticator. Now, every time you (or some bad guy with your password…) will try to log in to your SSH shell, you (or this bad guy) will be asked for authentication key in addition to traditional passphrase. |
| + | ||
| +Congratulations! You have just configured two factor authentication for SSH shell using Google Authenticator. Now, every time you (or some bad guy with your password…) will try to log in to your SSH shell, you (or this bad guy) will be asked for authentication key in addition to traditional passphrase. | ||
| + | ||
| +If you need some guidance on using two factor authentication, help is always at hand: |
m4sk1n
and others
added some commits
Dec 7, 2017
caldav
approved these changes
Dec 9, 2017
Thanks @m4sk1n! I'm merging it, it won't appear right away on the site as we are looking into making something a bit special for code-in students, probable by end of next week :)
m4sk1n commentedDec 4, 2017
#482
I'm waiting for feedback.
I will add two more screenshots from Authenticator app tomorrow and scale down the current one. I know my English isn't perfect…