[Summary view] [Print] [Text view]

   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  This sounds complicated, but in most cases it just means that Phabricator will
  13  make sure you have your mobile phone (by sending you a text message or having
  14  you enter a code from a mobile application) before allowing you to log in or
  15  take certain "high security" actions (like changing 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  Requiring re-authentication before performing high security actions further
  23  limits the damage an attacker can do even if they manage to compromise a
  24  login session.
  25  
  26  
  27  How Multi-Factor Authentication Works
  28  =====================================
  29  
  30  If you've configured multi-factor authentication and try to log in to your
  31  account or take certain high security actions (like changing your password),
  32  you'll be stopped and asked to enter additional credentials.
  33  
  34  Usually, this means you'll receive an SMS with a security code on your phone, or
  35  you'll open an app on your phone which will show you a security code.
  36  In both cases, you'll enter the security code into Phabricator.
  37  
  38  If you're logging in, Phabricator will log you in after you enter the code.
  39  
  40  If you're taking a high security action, Phabricator will put your account in
  41  "high security" mode for a few minutes. In this mode, you can take high security
  42  actions like changing passwords or SSH keys freely without entering any more
  43  credentials. You can explicitly leave high security once you're done performing
  44  account management, or your account will naturally return to normal security
  45  after a short period of time.
  46  
  47  While your account is in high security, you'll see a notification on screen
  48  with instructions for returning to normal security.
  49  
  50  
  51  Configuring Multi-Factor Authentication
  52  =======================================
  53  
  54  To manage authentication factors for your account, go to
  55  Settings > Multi-Factor Auth. You can use this control panel to add or remove
  56  authentication factors from your account.
  57  
  58  You can also rename a factor by clicking the name. This can help you identify
  59  factors if you have several similar factors attached to your account.
  60  
  61  For a description of the available factors, see the next few sections.
  62  
  63  
  64  Factor: Mobile Phone App (TOTP)
  65  ===============================
  66  
  67  TOTP stands for "Time-based One-Time Password". This factor operates by having
  68  you enter security codes from your mobile phone into Phabricator. The codes
  69  change every 30 seconds, so you will need to have your phone with you in order
  70  to enter them.
  71  
  72  To use this factor, you'll download an application onto your smartphone which
  73  can compute these codes. Two applications which work well are **Authy** and
  74  **Google Authenticator**. These applications are free, and you can find and
  75  download them from the appropriate store on your device.
  76  
  77  Your company may have a preferred application, or may use some other
  78  application, so check any in-house documentation for details. In general, any
  79  TOTP application should work properly.
  80  
  81  After you've downloaded the application onto your phone, use the Phabricator
  82  settings panel to add a factor to your account. You'll be prompted to enter a
  83  master key into your phone, and then read a security code from your phone and
  84  type it into Phabricator.
  85  
  86  Later, when you need to authenticate, you'll follow this same process: launch
  87  the application, read the security code, and type it into Phabricator. This will
  88  prove you have your phone.
  89  
  90  Don't lose your phone! You'll need it to log into Phabricator in the future.
  91  
  92  
  93  Recovering from Lost Factors
  94  ============================
  95  
  96  If you've lost a factor associated with your account (for example, your phone
  97  has been lost or damaged), an administrator can strip the factor off your
  98  account so that you can log in without it.
  99  
 100  IMPORTANT: Before stripping factors from a user account, be absolutely certain
 101  that the user is who they claim to be!
 102  
 103  It is important to verify the user is who they claim they are before stripping
 104  factors because an attacker might pretend to be a user who has lost their phone
 105  in order to bypass multi-factor authentication. It is much easier for a typical
 106  attacker to spoof an email with a sad story in it than it is for a typical
 107  attacker to gain access to a mobile phone.
 108  
 109  A good way to verify user identity is to meet them in person and have them
 110  solemnly swear an oath that they lost their phone and are very sorry and
 111  definitely won't do it again. You can also work out a secret handshake in
 112  advance and require them to perform it. But no matter what you do, be certain
 113  the user (not an attacker //pretending// to be the user) is really the one
 114  making the request before stripping factors.
 115  
 116  After verifying identity, administrators can strip authentication factors from
 117  user accounts using the `bin/auth strip` command. For example, to strip all
 118  factors from the account of a user who has lost their phone, run this command:
 119  
 120  ```lang=console
 121  # Strip all factors from a given user account.
 122  phabricator/ $ ./bin/auth strip --user <username> --all-types
 123  ```
 124  
 125  You can run `bin/auth help strip` for more detail and all available flags and
 126  arguments.
 127  
 128  This command can selectively strip types of factors. You can use
 129  `bin/auth list-factors` for a list of available factor types.
 130  
 131  ```lang=console
 132  # Show supported factor types.
 133  phabricator/ $ ./bin/auth list-factors
 134  ```