Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/field/revoking_credentials.diviner
- This file was added.
@title Revoking Credentials | |||||
@group fieldmanual | |||||
Revoking credentials, tokens, and sessions. | |||||
Overview | |||||
======== | |||||
If you've become aware of a security breach that affects you, you may want to | |||||
revoke or cycle credentials in case anything was leaked. | |||||
You can revoke credentials with the `bin/auth revoke` tool. This document | |||||
describes how to use the tool and how revocation works. | |||||
bin/auth revoke | |||||
=============== | |||||
The `bin/auth revoke` tool revokes specified sets of credentials from | |||||
specified targets. For example, if you believe `@alice` may have had her SSH | |||||
key compromised, you can revoke her keys like this: | |||||
``` | |||||
phabricator/ $ ./bin/auth revoke --type ssh --from @alice | |||||
``` | |||||
The flag `--everything` revokes all credential types. | |||||
The flag `--everywhere` revokes credentials from all objects. For most | |||||
credential types this means "all users", but some credentials (like SSH keys) | |||||
can also be associated with other kinds of objects. | |||||
Note that revocation can be disruptive (users must choose new passwords, | |||||
generate new API tokens, configure new SSH keys, etc) and can not be easily | |||||
undone if you perform an excessively broad revocation. | |||||
You can use the `--list` flag to get a list of available credential types | |||||
which can be revoked. This includes upstream credential types, and may include | |||||
third-party credential types if you have extensions installed. | |||||
amckinley: "extensions" | |||||
To list all revokable credential types: | |||||
``` | |||||
phabricator/ $ ./bin/auth revoke --list | |||||
``` | |||||
To get details about exactly how a specific revoker works: | |||||
``` | |||||
phabricator/ $ ./bin/auth revoke --list --type ssh | |||||
``` | |||||
Revocation vs Removal | |||||
===================== | |||||
Generally, `bin/auth revoke` **revokes** credentials, rather than just deleting | |||||
or removing them. That is, the credentials are moved to a permanent revocation | |||||
list of invalid credentials. | |||||
For example, revoking an SSH key prevents users from adding that key back to | |||||
their account: they must generate and add a new, unique key. Likewise, revoked | |||||
passwords can not be reused. | |||||
Although it is technically possible to reinstate credentials by removing them | |||||
from revocation lists, there are no tools available for this and you should | |||||
treat revocation lists as permanent. | |||||
Not Done Inline Actions"tooling"? amckinley: "tooling"? | |||||
Not Done Inline ActionsReworded "no toolset available" to "are no tools available". epriestley: Reworded "no toolset available" to "are no tools available". | |||||
Scenarios | |||||
========= | |||||
**Network Compromise**: If you believe you may have been affected by a network | |||||
compromise (where an attacker may have observed data transmitted over the | |||||
network), you should revoke the `password`, `conduit`, `session`, and | |||||
`temporary` credentials for all users. This will revoke all credentials which | |||||
are normally sent over the network. | |||||
Not Done Inline Actions"you should revoke" instead of "you may want to" amckinley: "you should revoke" instead of "you may want to" | |||||
Not Done Inline ActionsYeah, future changes and hypothetical third-party stuff excepted. epriestley: Yeah, future changes and hypothetical third-party stuff excepted. | |||||
You can revoke these credentials by running these commands: | |||||
``` | |||||
phabricator/ $ ./bin/auth revoke --type password --everywhere | |||||
phabricator/ $ ./bin/auth revoke --type conduit --everywhere | |||||
phabricator/ $ ./bin/auth revoke --type session --everywhere | |||||
phabricator/ $ ./bin/auth revoke --type temporary --everywhere | |||||
``` | |||||
Not Done Inline ActionsJust for the record, the result of the above is the same as --everything --everywhere, except the above keeps SSH keys, right? amckinley: Just for the record, the result of the above is the same as `--everything --everywhere`, except… | |||||
Depending on the nature of the compromise you may also consider revoking `ssh` | |||||
credentials, although these are usually not sent over the network because | |||||
they are asymmetric. | |||||
**User Compromise**: If you believe a user's credentials have been compromised | |||||
(for example, maybe they lost a phone or laptop) you should revoke | |||||
`--everything` from their account. This will revoke all of their outstanding | |||||
Not Done Inline Actions"If you believe a user's credentials have been compromised" makes more sense than "affected by a compromise". Also, "you should revoke" instead of "you may want to". amckinley: "If you believe a user's credentials have been compromised" makes more sense than "affected by… | |||||
credentials without affecting other users. | |||||
You can revoke all credentials for a user by running this command: | |||||
``` | |||||
phabricator/ $ ./bin/auth revoke --everything --from @alice | |||||
``` | |||||
Not Done Inline ActionsToo snarky for emergency documentation. amckinley: Too snarky for emergency documentation. |
"extensions"