Differential D25007 Diff 23 src/docs/user/userguide/multi_factor_auth.diviner

Changeset View

Standalone View

src/docs/user/userguide/multi_factor_auth.diviner

	@title User Guide: Multi-Factor Authentication			@title User Guide: Multi-Factor Authentication
	@group userguide			@group userguide

	Explains how multi-factor authentication works in Phabricator.			Explains how multi-factor authentication works in Phorge.

	Overview			Overview
	========			========

	Multi-factor authentication allows you to add additional credentials to your			Multi-factor authentication allows you to add additional credentials to your
	account to make it more secure.			account to make it more secure.

	Once multi-factor authentication is configured on your account, you'll usually			Once multi-factor authentication is configured on your account, you'll usually
	Show All 12 Lines

	If you've configured multi-factor authentication and try to log in to your			If you've configured multi-factor authentication and try to log in to your
	account or take certain sensitive actions (like changing your password),			account or take certain sensitive actions (like changing your password),
	you'll be stopped and asked to enter additional credentials.			you'll be stopped and asked to enter additional credentials.

	Usually, this means you'll receive an SMS with a authorization code on your			Usually, this means you'll receive an SMS with a authorization code on your
	phone, or you'll open an app on your phone which will show you a authorization			phone, or you'll open an app on your phone which will show you a authorization
	code or ask you to confirm the action. If you're given a authorization code,			code or ask you to confirm the action. If you're given a authorization code,
	you'll enter it into Phabricator.			you'll enter it into Phorge.

	If you're logging in, Phabricator will log you in after you enter the code.			If you're logging in, Phorge will log you in after you enter the code.

	If you're taking a sensitive action, Phabricator will sometimes put your			If you're taking a sensitive action, Phorge will sometimes put your
	account in "high security" mode for a few minutes. In this mode, you can take			account in "high security" mode for a few minutes. In this mode, you can take
	sensitive actions like changing passwords or SSH keys freely, without			sensitive actions like changing passwords or SSH keys freely, without
	entering any more credentials.			entering any more credentials.

	You can explicitly leave high security once you're done performing account			You can explicitly leave high security once you're done performing account
	management, or your account will naturally return to normal security after a			management, or your account will naturally return to normal security after a
	short period of time.			short period of time.

	Show All 13 Lines

	For a description of the available factors, see the next few sections.			For a description of the available factors, see the next few sections.


	Factor: Mobile Phone App (TOTP)			Factor: Mobile Phone App (TOTP)
	===============================			===============================

	TOTP stands for "Time-based One-Time Password". This factor operates by having			TOTP stands for "Time-based One-Time Password". This factor operates by having
	you enter authorization codes from your mobile phone into Phabricator. The codes			you enter authorization codes from your mobile phone into Phorge. The codes
	change every 30 seconds, so you will need to have your phone with you in order			change every 30 seconds, so you will need to have your phone with you in order
	to enter them.			to enter them.

	To use this factor, you'll download an application onto your smartphone which			To use this factor, you'll download an application onto your smartphone which
	can compute these codes. Two applications which work well are Authy and			can compute these codes. Two applications which work well are Authy and
	Google Authenticator. These applications are free, and you can find and			Google Authenticator. These applications are free, and you can find and
	download them from the appropriate store on your device.			download them from the appropriate store on your device.

	Your company may have a preferred application, or may use some other			Your company may have a preferred application, or may use some other
	application, so check any in-house documentation for details. In general, any			application, so check any in-house documentation for details. In general, any
	TOTP application should work properly.			TOTP application should work properly.

	After you've downloaded the application onto your phone, use the Phabricator			After you've downloaded the application onto your phone, use the Phorge
	settings panel to add a factor to your account. You'll be prompted to scan a			settings panel to add a factor to your account. You'll be prompted to scan a
	QR code, and then read an authorization code from your phone and type it into			QR code, and then read an authorization code from your phone and type it into
	Phabricator.			Phorge.

	Later, when you need to authenticate, you'll follow this same process: launch			Later, when you need to authenticate, you'll follow this same process: launch
	the application, read the authorization code, and type it into Phabricator.			the application, read the authorization code, and type it into Phorge.
	This will prove you have your phone.			This will prove you have your phone.

	Don't lose your phone! You'll need it to log into Phabricator in the future.			Don't lose your phone! You'll need it to log into Phorge in the future.


	Factor: SMS			Factor: SMS
	===========			===========

	This factor operates by texting you a short authorization code when you try to			This factor operates by texting you a short authorization code when you try to
	log in or perform a sensitive action.			log in or perform a sensitive action.

	Show All 20 Lines

	To use Duo, you'll install the Duo application on your phone. When you try			To use Duo, you'll install the Duo application on your phone. When you try
	to take a sensitive action, you'll be asked to confirm it in the application.			to take a sensitive action, you'll be asked to confirm it in the application.


	Administration: Configuration			Administration: Configuration
	=============================			=============================

	New Phabricator installs start without any multi-factor providers enabled.			New Phorge installs start without any multi-factor providers enabled.
	Users won't be able to add new factors until you set up multi-factor			Users won't be able to add new factors until you set up multi-factor
	authentication by configuring at least one provider.			authentication by configuring at least one provider.

	Configure new providers in {nav Auth > Multi-Factor}.			Configure new providers in {nav Auth > Multi-Factor}.

	Providers may be in these states:			Providers may be in these states:

	- Active: Users may add new factors. Users will be prompted to respond			- Active: Users may add new factors. Users will be prompted to respond
	▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines

	After verifying identity, administrators with host access can strip			After verifying identity, administrators with host access can strip
	authentication factors from user accounts using the `bin/auth strip` command.			authentication factors from user accounts using the `bin/auth strip` command.
	For example, to strip all factors from the account of a user who has lost			For example, to strip all factors from the account of a user who has lost
	their phone, run this command:			their phone, run this command:

	```lang=console			```lang=console
	# Strip all factors from a given user account.			# Strip all factors from a given user account.
	phabricator/ $ ./bin/auth strip --user <username> --all-types			phorge/ $ ./bin/auth strip --user <username> --all-types
	```			```

	You can run `bin/auth help strip` for more detail and all available flags and			You can run `bin/auth help strip` for more detail and all available flags and
	arguments.			arguments.

	This command can selectively strip factors by factor type. You can use			This command can selectively strip factors by factor type. You can use
	`bin/auth list-factors` to get a list of available factor types.			`bin/auth list-factors` to get a list of available factor types.

	```lang=console			```lang=console
	# Show supported factor types.			# Show supported factor types.
	phabricator/ $ ./bin/auth list-factors			phorge/ $ ./bin/auth list-factors
	```			```

	Once you've identified the factor types you want to strip, you can strip			Once you've identified the factor types you want to strip, you can strip
	matching factors by using the `--type` flag to specify one or more factor			matching factors by using the `--type` flag to specify one or more factor
	types:			types:

	```lang=console			```lang=console
	# Strip all SMS and TOTP factors for a user.			# Strip all SMS and TOTP factors for a user.
	phabricator/ $ ./bin/auth strip --user <username> --type sms --type totp			phorge/ $ ./bin/auth strip --user <username> --type sms --type totp
	```			```

	The `bin/auth strip` command can also selectively strip factors for certain			The `bin/auth strip` command can also selectively strip factors for certain
	providers. This is more granular than stripping all factors of a given type.			providers. This is more granular than stripping all factors of a given type.
	You can use `bin/auth list-mfa-providers` to get a list of providers.			You can use `bin/auth list-mfa-providers` to get a list of providers.

	Once you have a provider PHID, use `--provider` to select factors to strip:			Once you have a provider PHID, use `--provider` to select factors to strip:

	```lang=console			```lang=console
	# Strip all factors for a particular provider.			# Strip all factors for a particular provider.
	phabricator/ $ ./bin/auth strip --user <username> --provider <providerPHID>			phorge/ $ ./bin/auth strip --user <username> --provider <providerPHID>
	```			```