src/docs/user/userguide/multi_factor_auth.diviner

   1 @title User Guide: Multi-Factor Authentication
   2 @group userguide
   3
   4 Explains how multi-factor authentication works in Phabricator.
   5
   6 Overview
   7 ========
   8
   9 Multi-factor authentication allows you to add additional credentials to your
  10 account to make it more secure.
  11
  12 Once multi-factor authentication is configured on your account, you'll usually
  13 use your mobile phone to provide an authorization code or an extra confirmation
  14 when you try to log in to a new session or take certain actions (like changing
  15 your password).
  16
  17 Requiring you to prove you're really you by asking for something you know (your
  18 password) //and// something you have (your mobile phone) makes it much harder
  19 for attackers to access your account. The phone is an additional "factor" which
  20 protects your account from attacks.
  21
  22
  23 How Multi-Factor Authentication Works
  24 =====================================
  25
  26 If you've configured multi-factor authentication and try to log in to your
  27 account or take certain sensitive actions (like changing your password),
  28 you'll be stopped and asked to enter additional credentials.
  29
  30 Usually, this means you'll receive an SMS with a authorization code on your
  31 phone, or you'll open an app on your phone which will show you a authorization
  32 code or ask you to confirm the action. If you're given a authorization code,
  33 you'll enter it into Phabricator.
  34
  35 If you're logging in, Phabricator will log you in after you enter the code.
  36
  37 If you're taking a sensitive action, Phabricator will sometimes put your
  38 account in "high security" mode for a few minutes. In this mode, you can take
  39 sensitive actions like changing passwords or SSH keys freely, without
  40 entering any more credentials.
  41
  42 You can explicitly leave high security once you're done performing account
  43 management, or your account will naturally return to normal security after a
  44 short period of time.
  45
  46 While your account is in high security, you'll see a notification on screen
  47 with instructions for returning to normal security.
  48
  49
  50 Configuring Multi-Factor Authentication
  51 =======================================
  52
  53 To manage authentication factors for your account, go to
  54 {nav Settings > Multi-Factor Auth}. You can use this control panel to add
  55 or remove authentication factors from your account.
  56
  57 You can also rename a factor by clicking the name. This can help you identify
  58 factors if you have several similar factors attached to your account.
  59
  60 For a description of the available factors, see the next few sections.
  61
  62
  63 Factor: Mobile Phone App (TOTP)
  64 ===============================
  65
  66 TOTP stands for "Time-based One-Time Password". This factor operates by having
  67 you enter authorization codes from your mobile phone into Phabricator. The codes
  68 change every 30 seconds, so you will need to have your phone with you in order
  69 to enter them.
  70
  71 To use this factor, you'll download an application onto your smartphone which
  72 can compute these codes. Two applications which work well are **Authy** and
  73 **Google Authenticator**. These applications are free, and you can find and
  74 download them from the appropriate store on your device.
  75
  76 Your company may have a preferred application, or may use some other
  77 application, so check any in-house documentation for details. In general, any
  78 TOTP application should work properly.
  79
  80 After you've downloaded the application onto your phone, use the Phabricator
  81 settings panel to add a factor to your account. You'll be prompted to scan a
  82 QR code, and then read an authorization code from your phone and type it into
  83 Phabricator.
  84
  85 Later, when you need to authenticate, you'll follow this same process: launch
  86 the application, read the authorization code, and type it into Phabricator.
  87 This will prove you have your phone.
  88
  89 Don't lose your phone! You'll need it to log into Phabricator in the future.
  90
  91
  92 Factor: SMS
  93 ===========
  94
  95 This factor operates by texting you a short authorization code when you try to
  96 log in or perform a sensitive action.
  97
  98 To use SMS, first add your phone number in {nav Settings > Contact Numbers}.
  99 Once a primary contact number is configured on your account, you'll be able
 100 to add an SMS factor.
 101
 102 To enroll in SMS, you'll be sent a confirmation code to make sure your contact
 103 number is correct and SMS is being delivered properly. Enter it when prompted.
 104
 105 When you're asked to confirm your identity in the future, you'll be texted
 106 an authorization code to enter into the prompt.
 107
 108 (WARNING) SMS is a very weak factor and can be compromised or intercepted. For
 109 details, see: <https://phurl.io/u/sms>.
 110
 111
 112 Factor: Duo
 113 ===========
 114
 115 This factor supports integration with [[ https://duo.com/ | Duo Security ]], a
 116 third-party authentication service popular with enterprises that have a lot of
 117 policies to enforce.
 118
 119 To use Duo, you'll install the Duo application on your phone. When you try
 120 to take a sensitive action, you'll be asked to confirm it in the application.
 121
 122
 123 Administration: Configuration
 124 =============================
 125
 126 New Phabricator installs start without any multi-factor providers enabled.
 127 Users won't be able to add new factors until you set up multi-factor
 128 authentication by configuring at least one provider.
 129
 130 Configure new providers in {nav Auth > Multi-Factor}.
 131
 132 Providers may be in these states:
 133
 134   - **Active**: Users may add new factors. Users will be prompted to respond
 135     to challenges from these providers when they take a sensitive action.
 136   - **Deprecated**: Users may not add new factors, but they will still be
 137     asked to respond to challenges from exising factors.
 138   - **Disabled**: Users may not add new factors, and existing factors will
 139     not be used. If MFA is required and a user only has disabled factors,
 140     they will be forced to add a new factor.
 141
 142 If you want to change factor types for your organization, the process will
 143 normally look something like this:
 144
 145   - Configure and test a new provider.
 146   - Deprecate the old provider.
 147   - Notify users that the old provider is deprecated and that they should move
 148     to the new provider at their convenience, but before some upcoming
 149     deadline.
 150   - Once the deadline arrives, disable the old provider.
 151
 152
 153 Administration: Requiring MFA
 154 =============================
 155
 156 As an administrator, you can require all users to add MFA to their accounts by
 157 setting the `security.require-multi-factor-auth` option in Config.
 158
 159
 160 Administration: Recovering from Lost Factors
 161 ============================================
 162
 163 If a user has lost a factor associated with their account (for example, their
 164 phone has been lost or damaged), an administrator with host access can strip
 165 the factor off their account so that they can log in without it.
 166
 167 IMPORTANT: Before stripping factors from a user account, be absolutely certain
 168 that the user is who they claim to be!
 169
 170 It is important to verify the user is who they claim they are before stripping
 171 factors because an attacker might pretend to be a user who has lost their phone
 172 in order to bypass multi-factor authentication. It is much easier for a typical
 173 attacker to spoof an email with a sad story in it than it is for a typical
 174 attacker to gain access to a mobile phone.
 175
 176 A good way to verify user identity is to meet them in person and have them
 177 solemnly swear an oath that they lost their phone and are very sorry and
 178 definitely won't do it again. You can also work out a secret handshake in
 179 advance and require them to perform it. But no matter what you do, be certain
 180 the user (not an attacker //pretending// to be the user) is really the one
 181 making the request before stripping factors.
 182
 183 After verifying identity, administrators with host access can strip
 184 authentication factors from user accounts using the `bin/auth strip` command.
 185 For example, to strip all factors from the account of a user who has lost
 186 their phone, run this command:
 187
 188 ```lang=console
 189 # Strip all factors from a given user account.
 190 phabricator/ $ ./bin/auth strip --user <username> --all-types
 191 ```
 192
 193 You can run `bin/auth help strip` for more detail and all available flags and
 194 arguments.
 195
 196 This command can selectively strip factors by factor type. You can use
 197 `bin/auth list-factors` to get a list of available factor types.
 198
 199 ```lang=console
 200 # Show supported factor types.
 201 phabricator/ $ ./bin/auth list-factors
 202 ```
 203
 204 Once you've identified the factor types you want to strip, you can strip
 205 matching factors by using the `--type` flag to specify one or more factor
 206 types:
 207
 208 ```lang=console
 209 # Strip all SMS and TOTP factors for a user.
 210 phabricator/ $ ./bin/auth strip --user <username> --type sms --type totp
 211 ```
 212
 213 The `bin/auth strip` command can also selectively strip factors for certain
 214 providers. This is more granular than stripping all factors of a given type.
 215 You can use `bin/auth list-mfa-providers` to get a list of providers.
 216
 217 Once you have a provider PHID, use `--provider` to select factors to strip:
 218
 219 ```lang=console
 220 # Strip all factors for a particular provider.
 221 phabricator/ $ ./bin/auth strip --user <username> --provider <providerPHID>
 222 ```