Something went wrong. Try again.
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.) hq.recaptime.dev/wiki/Phorge
phorge phabricator
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223@title User Guide: Multi-Factor Authentication@group userguideExplains how multi-factor authentication works in Phorge.Overview========Multi-factor authentication allows you to add additional credentials to youraccount to make it more secure.Once multi-factor authentication is configured on your account, you'll usuallyuse your mobile phone to provide an authorization code or an extra confirmationwhen you try to log in to a new session or take certain actions (like changingyour password).Requiring you to prove you're really you by asking for something you know (yourpassword) //and// something you have (your mobile phone) makes it much harderfor attackers to access your account. The phone is an additional "factor" whichprotects your account from attacks.How Multi-Factor Authentication Works=====================================If you've configured multi-factor authentication and try to log in to youraccount or take certain sensitive actions (like changing your password),you'll be stopped and asked to enter additional credentials.Usually, this means you'll receive an SMS with a authorization code on yourphone, or you'll open an app on your phone which will show you a authorizationcode or ask you to confirm the action. If you're given a authorization code,you'll enter it into Phorge.If you're logging in, Phorge will log you in after you enter the code.If you're taking a sensitive action, Phorge will sometimes put youraccount in "high security" mode for a few minutes. In this mode, you can takesensitive actions like changing passwords or SSH keys freely, withoutentering any more credentials.You can explicitly leave high security once you're done performing accountmanagement, or your account will naturally return to normal security after ashort period of time.While your account is in high security, you'll see a notification on screenwith instructions for returning to normal security.Configuring Multi-Factor Authentication=======================================To manage authentication factors for your account, go to{nav Settings > Multi-Factor Auth}. You can use this control panel to addor remove authentication factors from your account.You can also rename a factor by clicking the name. This can help you identifyfactors if you have several similar factors attached to your account.For a description of the available factors, see the next few sections.Factor: Mobile Phone App (TOTP)===============================TOTP stands for "Time-based One-Time Password". This factor operates by havingyou enter authorization codes from your mobile phone into Phorge. The codeschange every 30 seconds, so you will need to have your phone with you in orderto enter them.To use this factor, you'll download an application onto your smartphone whichcan compute these codes. Two applications which work well are **Authy** and**Google Authenticator**. These applications are free, and you can find anddownload them from the appropriate store on your device.Your company may have a preferred application, or may use some otherapplication, so check any in-house documentation for details. In general, anyTOTP application should work properly.After you've downloaded the application onto your phone, use the Phorgesettings panel to add a factor to your account. You'll be prompted to scan aQR code, and then read an authorization code from your phone and type it intoPhorge.Later, when you need to authenticate, you'll follow this same process: launchthe application, read the authorization code, and type it into Phorge.This will prove you have your phone.Don't lose your phone! You'll need it to log into Phorge in the future.Factor: SMS===========This factor operates by texting you a short authorization code when you try tolog in or perform a sensitive action.To use SMS, first add your phone number in {nav Settings > Contact Numbers}.Once a primary contact number is configured on your account, you'll be ableto add an SMS factor.To enroll in SMS, you'll be sent a confirmation code to make sure your contactnumber is correct and SMS is being delivered properly. Enter it when prompted.When you're asked to confirm your identity in the future, you'll be textedan authorization code to enter into the prompt.(WARNING) SMS is a very weak factor and can be compromised or intercepted. Fordetails, see: <https://secure.phabricator.com/T13241>.Factor: Duo===========This factor supports integration with [[ https://duo.com/ | Duo Security ]], athird-party authentication service popular with enterprises that have a lot ofpolicies to enforce.To use Duo, you'll install the Duo application on your phone. When you tryto take a sensitive action, you'll be asked to confirm it in the application.Administration: Configuration=============================New Phorge installs start without any multi-factor providers enabled.Users won't be able to add new factors until you set up multi-factorauthentication by configuring at least one provider.Configure new providers in {nav Auth > Multi-Factor}.Providers may be in these states: - **Active**: Users may add new factors. Users will be prompted to respond to challenges from these providers when they take a sensitive action. - **Deprecated**: Users may not add new factors, but they will still be asked to respond to challenges from existing factors. - **Disabled**: Users may not add new factors, and existing factors will not be used. If MFA is required and a user only has disabled factors, they will be forced to add a new factor.If you want to change factor types for your organization, the process willnormally look something like this: - Configure and test a new provider. - Deprecate the old provider. - Notify users that the old provider is deprecated and that they should move to the new provider at their convenience, but before some upcoming deadline. - Once the deadline arrives, disable the old provider.Administration: Requiring MFA=============================As an administrator, you can require all users to add MFA to their accounts bysetting the `security.require-multi-factor-auth` option in Config.Administration: Recovering from Lost Factors============================================If a user has lost a factor associated with their account (for example, theirphone has been lost or damaged), an administrator with host access can stripthe factor off their account so that they can log in without it.IMPORTANT: Before stripping factors from a user account, be absolutely certainthat the user is who they claim to be!It is important to verify the user is who they claim they are before strippingfactors because an attacker might pretend to be a user who has lost their phonein order to bypass multi-factor authentication. It is much easier for a typicalattacker to spoof an email with a sad story in it than it is for a typicalattacker to gain access to a mobile phone.A good way to verify user identity is to meet them in person and have themsolemnly swear an oath that they lost their phone and are very sorry anddefinitely won't do it again. You can also work out a secret handshake inadvance and require them to perform it. But no matter what you do, be certainthe user (not an attacker //pretending// to be the user) is really the onemaking the request before stripping factors.After verifying identity, administrators with host access can stripauthentication factors from user accounts using the `bin/auth strip` command.For example, to strip all factors from the account of a user who has losttheir phone, run this command:```lang=console# Strip all factors from a given user account.phorge/ $ ./bin/auth strip --user <username> --all-types```You can run `bin/auth help strip` for more detail and all available flags andarguments.This command can selectively strip factors by factor type. You can use`bin/auth list-factors` to get a list of available factor types.```lang=console# Show supported factor types.phorge/ $ ./bin/auth list-factors```Once you've identified the factor types you want to strip, you can stripmatching factors by using the `--type` flag to specify one or more factortypes:```lang=console# Strip all SMS and TOTP factors for a user.phorge/ $ ./bin/auth strip --user <username> --type sms --type totp```The `bin/auth strip` command can also selectively strip factors for certainproviders. 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.Once you have a provider PHID, use `--provider` to select factors to strip:```lang=console# Strip all factors for a particular provider.phorge/ $ ./bin/auth strip --user <username> --provider <providerPHID>```