@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+150
-2
+16
-2
src/applications/settings/panel/PhabricatorSettingsPanelMultiFactor.php
+16
-2
src/applications/settings/panel/PhabricatorSettingsPanelMultiFactor.php
···
104
104
$panel = new PHUIObjectBoxView();
105
105
$header = new PHUIHeaderView();
106
106
107
+
$help_uri = PhabricatorEnv::getDoclink(
108
+
'User Guide: Multi-Factor Authentication');
109
+
110
+
$help_icon = id(new PHUIIconView())
111
+
->setSpriteSheet(PHUIIconView::SPRITE_ICONS)
112
+
->setSpriteIcon('lint-info');
113
+
$help_button = id(new PHUIButtonView())
114
+
->setText(pht('Help'))
115
+
->setHref($help_uri)
116
+
->setTag('a')
117
+
->setIcon($help_icon);
118
+
107
119
$create_icon = id(new PHUIIconView())
108
120
->setSpriteSheet(PHUIIconView::SPRITE_ICONS)
109
121
->setSpriteIcon('new');
···
115
127
->setIcon($create_icon);
116
128
117
129
$header->setHeader(pht('Authentication Factors'));
130
+
$header->addActionLink($help_button);
118
131
$header->addActionLink($create_button);
119
132
120
133
$panel->setHeader($header);
···
162
175
163
176
$dialog->appendParagraph(
164
177
pht(
165
-
'Adding an additional authentication factor increases the security '.
166
-
'of your account.'));
178
+
'Adding an additional authentication factor improves the security '.
179
+
'of your account. Choose the type of factor to add:'));
167
180
168
181
$form
169
182
->appendChild($choice_control);
183
+
170
184
} else {
171
185
$dialog->addHiddenInput('type', $type);
172
186
+134
src/docs/user/userguide/multi_factor_auth.diviner
+134
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
+
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
+
```