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 ```