Differential D18911 Diff 45329 src/docs/user/field/revoking_credentials.diviner

Changeset 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 extension installed.

				amckinleyUnsubmitted Not Done Inline Actions "extensions" amckinley: "extensions"

				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 removal is technically possible, there is no toolset available for
				removing credentials from revocation lists.


				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 may want to revoke the `password`, `conduit`, `session`, and
				`temporary` credentials for all users. This will revoke all credentials which
				are normally sent over the network.

				Depending on the nature of the compromise you may consider revoking `ssh`
				credentials, although these are usually not sent over the network because
				amckinleyUnsubmitted Not Done Inline Actions "tooling"? amckinley: "tooling"?
				epriestleyAuthorUnsubmitted Not Done Inline Actions Reworded "no toolset available" to "are no tools available". epriestley: Reworded "no toolset available" to "are no tools available".
				they are asymmetric.

				You might do this with 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
				```
				amckinleyUnsubmitted Not Done Inline Actions "you should revoke" instead of "you may want to" amckinley: "you should revoke" instead of "you may want to"
				epriestleyAuthorUnsubmitted Not Done Inline Actions Yeah, future changes and hypothetical third-party stuff excepted. epriestley: Yeah, future changes and hypothetical third-party stuff excepted.

				User Compromise: If you believe a user may have been affected by a
				compromise (for example, maybe they lost a phone or laptop) you may want to
				revoke `--everything` from their account. This will revoke all of their
				outstanding credentials without affecting other users.

				You might do this with this command:

				```
				amckinleyUnsubmitted Not Done Inline Actions Just 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…
				phabricator/ $ ./bin/auth revoke --everything --from @alice
				```

				I Am The Law: If you want to impress users with your powerful security
				policy, routinely revoke `--everything --everywhere` to keep everyone on their
				toes.
				amckinleyUnsubmitted 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…
				amckinleyUnsubmitted Not Done Inline Actions Too snarky for emergency documentation. amckinley: Too snarky for emergency documentation.