Revoking Credentials

Phorge Administrator and User Documentation (Field Manuals)

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:

phorge/ $ ./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.

To list all revokable credential types:

phorge/ $ ./bin/auth revoke --list

To get details about exactly how a specific revoker works:

phorge/ $ ./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.

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.

You can revoke these credentials by running these commands:

phorge/ $ ./bin/auth revoke --type password --everywhere
phorge/ $ ./bin/auth revoke --type conduit --everywhere
phorge/ $ ./bin/auth revoke --type session --everywhere
phorge/ $ ./bin/auth revoke --type temporary --everywhere

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 credentials without affecting other users.

You can revoke all credentials for a user by running this command:

phorge/ $ ./bin/auth revoke --everything --from @alice