@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 the "bin/auth revoke" tool
Summary: Depends on D18910. Ref T13043. Provides reasonable user-facing documentation about the general role and utility of this tool.
Test Plan: Read document.
Reviewers: amckinley
Reviewed By: amckinley
Maniphest Tasks: T13043
Differential Revision: https://secure.phabricator.com/D18911
+101
+101
src/docs/user/field/revoking_credentials.diviner
+101
src/docs/user/field/revoking_credentials.diviner
···
1
+
@title Revoking Credentials
2
+
@group fieldmanual
3
+
4
+
Revoking credentials, tokens, and sessions.
5
+
6
+
Overview
7
+
========
8
+
9
+
If you've become aware of a security breach that affects you, you may want to
10
+
revoke or cycle credentials in case anything was leaked.
11
+
12
+
You can revoke credentials with the `bin/auth revoke` tool. This document
13
+
describes how to use the tool and how revocation works.
14
+
15
+
16
+
bin/auth revoke
17
+
===============
18
+
19
+
The `bin/auth revoke` tool revokes specified sets of credentials from
20
+
specified targets. For example, if you believe `@alice` may have had her SSH
21
+
key compromised, you can revoke her keys like this:
22
+
23
+
```
24
+
phabricator/ $ ./bin/auth revoke --type ssh --from @alice
25
+
```
26
+
27
+
The flag `--everything` revokes all credential types.
28
+
29
+
The flag `--everywhere` revokes credentials from all objects. For most
30
+
credential types this means "all users", but some credentials (like SSH keys)
31
+
can also be associated with other kinds of objects.
32
+
33
+
Note that revocation can be disruptive (users must choose new passwords,
34
+
generate new API tokens, configure new SSH keys, etc) and can not be easily
35
+
undone if you perform an excessively broad revocation.
36
+
37
+
You can use the `--list` flag to get a list of available credential types
38
+
which can be revoked. This includes upstream credential types, and may include
39
+
third-party credential types if you have extensions installed.
40
+
41
+
To list all revokable credential types:
42
+
43
+
```
44
+
phabricator/ $ ./bin/auth revoke --list
45
+
```
46
+
47
+
To get details about exactly how a specific revoker works:
48
+
49
+
```
50
+
phabricator/ $ ./bin/auth revoke --list --type ssh
51
+
```
52
+
53
+
54
+
Revocation vs Removal
55
+
=====================
56
+
57
+
Generally, `bin/auth revoke` **revokes** credentials, rather than just deleting
58
+
or removing them. That is, the credentials are moved to a permanent revocation
59
+
list of invalid credentials.
60
+
61
+
For example, revoking an SSH key prevents users from adding that key back to
62
+
their account: they must generate and add a new, unique key. Likewise, revoked
63
+
passwords can not be reused.
64
+
65
+
Although it is technically possible to reinstate credentials by removing them
66
+
from revocation lists, there are no tools available for this and you should
67
+
treat revocation lists as permanent.
68
+
69
+
70
+
Scenarios
71
+
=========
72
+
73
+
**Network Compromise**: If you believe you may have been affected by a network
74
+
compromise (where an attacker may have observed data transmitted over the
75
+
network), you should revoke the `password`, `conduit`, `session`, and
76
+
`temporary` credentials for all users. This will revoke all credentials which
77
+
are normally sent over the network.
78
+
79
+
You can revoke these credentials by running these commands:
80
+
81
+
```
82
+
phabricator/ $ ./bin/auth revoke --type password --everywhere
83
+
phabricator/ $ ./bin/auth revoke --type conduit --everywhere
84
+
phabricator/ $ ./bin/auth revoke --type session --everywhere
85
+
phabricator/ $ ./bin/auth revoke --type temporary --everywhere
86
+
```
87
+
88
+
Depending on the nature of the compromise you may also consider revoking `ssh`
89
+
credentials, although these are usually not sent over the network because
90
+
they are asymmetric.
91
+
92
+
**User Compromise**: If you believe a user's credentials have been compromised
93
+
(for example, maybe they lost a phone or laptop) you should revoke
94
+
`--everything` from their account. This will revoke all of their outstanding
95
+
credentials without affecting other users.
96
+
97
+
You can revoke all credentials for a user by running this command:
98
+
99
+
```
100
+
phabricator/ $ ./bin/auth revoke --everything --from @alice
101
+
```