@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
Update documentation for MFA, including administrator guidance
Summary: Depends on D20032. Ref T13222.
Test Plan: Read documentation.
Reviewers: amckinley
Reviewed By: amckinley
Maniphest Tasks: T13222
Differential Revision: https://secure.phabricator.com/D20033
+95
-37
+95
-37
src/docs/user/userguide/multi_factor_auth.diviner
+95
-37
src/docs/user/userguide/multi_factor_auth.diviner
···
9
9
Multi-factor authentication allows you to add additional credentials to your
10
10
account to make it more secure.
11
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).
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
16
17
17
Requiring you to prove you're really you by asking for something you know (your
18
18
password) //and// something you have (your mobile phone) makes it much harder
19
19
for attackers to access your account. The phone is an additional "factor" which
20
20
protects your account from attacks.
21
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
22
27
23
How Multi-Factor Authentication Works
28
24
=====================================
29
25
30
26
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),
27
+
account or take certain sensitive actions (like changing your password),
32
28
you'll be stopped and asked to enter additional credentials.
33
29
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.
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.
37
34
38
35
If you're logging in, Phabricator will log you in after you enter the code.
39
36
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.
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.
46
45
47
46
While your account is in high security, you'll see a notification on screen
48
47
with instructions for returning to normal security.
···
52
51
=======================================
53
52
54
53
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.
54
+
{nav Settings > Multi-Factor Auth}. You can use this control panel to add
55
+
or remove authentication factors from your account.
57
56
58
57
You can also rename a factor by clicking the name. This can help you identify
59
58
factors if you have several similar factors attached to your account.
···
65
64
===============================
66
65
67
66
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
67
+
you enter authorization codes from your mobile phone into Phabricator. The codes
69
68
change every 30 seconds, so you will need to have your phone with you in order
70
69
to enter them.
71
70
···
79
78
TOTP application should work properly.
80
79
81
80
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.
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.
85
84
86
85
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.
86
+
the application, read the authorization code, and type it into Phabricator.
87
+
This will prove you have your phone.
89
88
90
89
Don't lose your phone! You'll need it to log into Phabricator in the future.
91
90
92
91
93
-
Recovering from Lost Factors
94
-
============================
92
+
Factor: SMS
93
+
===========
95
94
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.
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
+
Administration: Configuration
113
+
=============================
114
+
115
+
New Phabricator installs start without any multi-factor providers enabled.
116
+
Users won't be able to add new factors until you set up multi-factor
117
+
authentication by configuring at least one provider.
118
+
119
+
Configure new providers in {nav Auth > Multi-Factor}.
120
+
121
+
Providers may be in these states:
122
+
123
+
- **Active**: Users may add new factors. Users will be prompted to respond
124
+
to challenges from these providers when they take a sensitive action.
125
+
- **Deprecated**: Users may not add new factors, but they will still be
126
+
asked to respond to challenges from exising factors.
127
+
- **Disabled**: Users may not add new factors, and existing factors will
128
+
not be used. If MFA is required and a user only has disabled factors,
129
+
they will be forced to add a new factor.
130
+
131
+
If you want to change factor types for your organization, the process will
132
+
normally look something like this:
133
+
134
+
- Configure and test a new provider.
135
+
- Deprecate the old provider.
136
+
- Notify users that the old provider is deprecated and that they should move
137
+
to the new provider at their convenience, but before some upcoming
138
+
deadline.
139
+
- Once the deadline arrives, disable the old provider.
140
+
141
+
142
+
Administration: Requiring MFA
143
+
=============================
144
+
145
+
As an administrator, you can require all users to add MFA to their accounts by
146
+
setting the `security.require-multi-factor-auth` option in Config.
147
+
148
+
149
+
Administration: Recovering from Lost Factors
150
+
============================================
151
+
152
+
If a user has lost a factor associated with their account (for example, their
153
+
phone has been lost or damaged), an administrator with host access can strip
154
+
the factor off their account so that they can log in without it.
99
155
100
156
IMPORTANT: Before stripping factors from a user account, be absolutely certain
101
157
that the user is who they claim to be!
···
113
169
the user (not an attacker //pretending// to be the user) is really the one
114
170
making the request before stripping factors.
115
171
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:
172
+
After verifying identity, administrators with host access can strip
173
+
authentication factors from user accounts using the `bin/auth strip` command.
174
+
For example, to strip all factors from the account of a user who has lost
175
+
their phone, run this command:
119
176
120
177
```lang=console
121
178
# Strip all factors from a given user account.
···
125
182
You can run `bin/auth help strip` for more detail and all available flags and
126
183
arguments.
127
184
128
-
This command can selectively strip types of factors. You can use
185
+
This command can selectively strip factors by factor type. You can use
129
186
`bin/auth list-factors` to get a list of available factor types.
130
187
131
188
```lang=console
···
133
190
phabricator/ $ ./bin/auth list-factors
134
191
```
135
192
136
-
Once you've identified the factor types you want to strip, you can strip them
137
-
using the `--type` flag to specify one or more factor types:
193
+
Once you've identified the factor types you want to strip, you can strip
194
+
matching factors by using the `--type` flag to specify one or more factor
195
+
types:
138
196
139
197
```lang=console
140
198
# Strip all SMS and TOTP factors for a user.