From 68023e64a9223ca12d5e593a9953595f3aaf3715 Mon Sep 17 00:00:00 2001 From: epriestley Date: Thu, 1 May 2014 10:23:41 -0700 Subject: [PATCH] Document multi-factor authentication Summary: Ref T4398. This has a few lies (in the sense of "features that don't work yet") but should describe behavior accurately after a few more patches. Test Plan: Read it. Reviewers: btrahan Reviewed By: btrahan Subscribers: epriestley Maniphest Tasks: T4398 Differential Revision: https://secure.phabricator.com/D8910 --- .../PhabricatorSettingsPanelMultiFactor.php | 18 ++- .../user/userguide/multi_factor_auth.diviner | 134 ++++++++++++++++++ 2 files changed, 150 insertions(+), 2 deletions(-) create mode 100644 src/docs/user/userguide/multi_factor_auth.diviner diff --git a/src/applications/settings/panel/PhabricatorSettingsPanelMultiFactor.php b/src/applications/settings/panel/PhabricatorSettingsPanelMultiFactor.php index 0ba72962c1..716026da2e 100644 --- a/src/applications/settings/panel/PhabricatorSettingsPanelMultiFactor.php +++ b/src/applications/settings/panel/PhabricatorSettingsPanelMultiFactor.php @@ -104,6 +104,18 @@ final class PhabricatorSettingsPanelMultiFactor $panel = new PHUIObjectBoxView(); $header = new PHUIHeaderView(); + $help_uri = PhabricatorEnv::getDoclink( + 'User Guide: Multi-Factor Authentication'); + + $help_icon = id(new PHUIIconView()) + ->setSpriteSheet(PHUIIconView::SPRITE_ICONS) + ->setSpriteIcon('lint-info'); + $help_button = id(new PHUIButtonView()) + ->setText(pht('Help')) + ->setHref($help_uri) + ->setTag('a') + ->setIcon($help_icon); + $create_icon = id(new PHUIIconView()) ->setSpriteSheet(PHUIIconView::SPRITE_ICONS) ->setSpriteIcon('new'); @@ -115,6 +127,7 @@ final class PhabricatorSettingsPanelMultiFactor ->setIcon($create_icon); $header->setHeader(pht('Authentication Factors')); + $header->addActionLink($help_button); $header->addActionLink($create_button); $panel->setHeader($header); @@ -162,11 +175,12 @@ final class PhabricatorSettingsPanelMultiFactor $dialog->appendParagraph( pht( - 'Adding an additional authentication factor increases the security '. - 'of your account.')); + 'Adding an additional authentication factor improves the security '. + 'of your account. Choose the type of factor to add:')); $form ->appendChild($choice_control); + } else { $dialog->addHiddenInput('type', $type); diff --git a/src/docs/user/userguide/multi_factor_auth.diviner b/src/docs/user/userguide/multi_factor_auth.diviner new file mode 100644 index 0000000000..c17c80d296 --- /dev/null +++ b/src/docs/user/userguide/multi_factor_auth.diviner @@ -0,0 +1,134 @@ +@title User Guide: Multi-Factor Authentication +@group userguide + +Explains how multi-factor authentication works in Phabricator. + +Overview +======== + +Multi-factor authentication allows you to add additional credentials to your +account to make it more secure. + +This sounds complicated, but in most cases it just means that Phabricator will +make sure you have your mobile phone (by sending you a text message or having +you enter a code from a mobile application) before allowing you to log in or +take certain "high security" actions (like changing your password). + +Requiring you to prove you're really you by asking for something you know (your +password) //and// something you have (your mobile phone) makes it much harder +for attackers to access your account. The phone is an additional "factor" which +protects your account from attacks. + +Requiring re-authentication before performing high security actions further +limits the damage an attacker can do even if they manage to compromise a +login session. + + +How Multi-Factor Authentication Works +===================================== + +If you've configured multi-factor authentication and try to log in to your +account or take certain high security actions (like changing your password), +you'll be stopped and asked to enter additional credentials. + +Usually, this means you'll receive an SMS with a security code on your phone, or +you'll open an app on your phone which will show you a security code. +In both cases, you'll enter the security code into Phabricator. + +If you're logging in, Phabricator will log you in after you enter the code. + +If you're taking a high security action, Phabricator will put your account in +"high security" mode for a few minutes. In this mode, you can take high security +actions like changing passwords or SSH keys freely without entering any more +credentials. You can explicitly leave high security once you're done performing +account management, or your account will naturally return to normal security +after a short period of time. + +While your account is in high security, you'll see a notification on screen +with instructions for returning to normal security. + + +Configuring Multi-Factor Authentication +======================================= + +To manage authentication factors for your account, go to +Settings > Multi-Factor Auth. You can use this control panel to add or remove +authentication factors from your account. + +You can also rename a factor by clicking the name. This can help you identify +factors if you have several similar factors attached to your account. + +For a description of the available factors, see the next few sections. + + +Factor: Mobile Phone App (TOTP) +=============================== + +TOTP stands for "Time-based One-Time Password". This factor operates by having +you enter security codes from your mobile phone into Phabricator. The codes +change every 30 seconds, so you will need to have your phone with you in order +to enter them. + +To use this factor, you'll download an application onto your smartphone which +can compute these codes. Two applications which work well are **Authy** and +**Google Authenticator**. These applications are free, and you can find and +download them from the appropriate store on your device. + +Your company may have a preferred application, or may use some other +application, so check any in-house documentation for details. In general, any +TOTP application should work properly. + +After you've downloaded the application onto your phone, use the Phabricator +settings panel to add a factor to your account. You'll be prompted to enter a +master key into your phone, and then read a security code from your phone and +type it into Phabricator. + +Later, when you need to authenticate, you'll follow this same process: launch +the application, read the security code, and type it into Phabricator. This will +prove you have your phone. + +Don't lose your phone! You'll need it to log into Phabricator in the future. + + +Recovering from Lost Factors +============================ + +If you've lost a factor associated with your account (for example, your phone +has been lost or damaged), an administrator can strip the factor off your +account so that you can log in without it. + +IMPORTANT: Before stripping factors from a user account, be absolutely certain +that the user is who they claim to be! + +It is important to verify the user is who they claim they are before stripping +factors because an attacker might pretend to be a user who has lost their phone +in order to bypass multi-factor authentication. It is much easier for a typical +attacker to spoof an email with a sad story in it than it is for a typical +attacker to gain access to a mobile phone. + +A good way to verify user identity is to meet them in person and have them +solemnly swear an oath that they lost their phone and are very sorry and +definitely won't do it again. You can also work out a secret handshake in +advance and require them to perform it. But no matter what you do, be certain +the user (not an attacker //pretending// to be the user) is really the one +making the request before stripping factors. + +After verifying identity, administrators can strip authentication factors from +user accounts using the `bin/auth strip` command. For example, to strip all +factors from the account of a user who has lost their phone, run this command: + +```lang=console +# Strip all factors from a given user account. +phabricator/ $ ./bin/auth strip --user --all-types +``` + +You can run `bin/auth help strip` for more detail and all available flags and +arguments. + +This command can selectively strip types of factors. You can use +`bin/auth list-factors` for a list of available factor types. + +```lang=console +# Show supported factor types. +phabricator/ $ ./bin/auth list-factors +```