View source for Help:Two-factor authentication

{{seealso|:meta:Help:Two-factor authentication}}
{{Infopage|H:2FA|WP:2FA}}
{{nutshell|Administrators and editors with advanced permissions should ideally enable two-factor authentication for account security, and can do so by following this guide.}}
{{warning|'''Particular attention''' should be paid to the section of this guide on [[#Recovery codes|recovery codes]] — if you don't keep these codes and encounter a problem with your 2FA device, you will be locked out of your account.}}
[[File:Différents modèles de lecteurs de cartes bancaires.jpg|thumb|240px|2FA is like a software version of the [[security token]] devices used for online banking in some countries.]]
'''[[Multi-factor authentication|Two-factor authentication]]''' ('''2FA''') is a method of adding additional security to your account. The first "factor" is your usual password that is standard for any account. The second "factor" is a verification code retrieved from an app on a mobile device or computer. 2FA is conceptually similar to a [[security token]] device that banks in some countries require for [[online banking]]. Other names for 2FA systems include ''OTP'' (''[[one-time password]]'') and ''TOTP'' (''[[Time-based One-time Password algorithm]]'').

This guide explains how to enable and disable 2FA on RetroWikipedia for your account.  This guide is about the TOTP method, see notes about WebAuthn below.

If you decide to enable 2FA, you may want to enable the option "Send password reset emails only when both email address and username are provided" in the first tab of [[Special:Preferences]].

== Securing your account ==
{{seealso|RetroWikipedia:User account security}}
[[File:Basic information in RetroWikipedia preferences.png|thumb|[[H:P|Preferences]] with button to enable 2FA]]
It is '''extremely important''' for administrators and editors with advanced permissions to keep their account secure. A number of RetroWikipedia administrators (including the co-founder, {{u|Jimbo Wales}}) have had their accounts compromised, which were then used to vandalise the encyclopedia. As well as causing widespread disruption, the affected administrators' accounts were locked until it was beyond doubt they had regained control.

Any editor can improve their [[RetroWikipedia:User account security|account security]] by using 2FA. This practice is recommended for editors with advanced permissions, highly recommended for administrators, and required for interface administrators, among others.

Before enabling 2FA, please ensure that you have a [[Password strength|strong password]] that is exclusively used for RetroWikipedia. Consider using a [[password manager]] to generate strong, unique passwords for each of your online accounts.

== Accessing 2FA ==
{{main article|m:Help:Two-factor authentication#Accounts affected}}
{{shortcut|H:ACCESS2FA}}
On the English RetroWikipedia, the following groups automatically have access to 2FA:

* [[RetroWikipedia:Administrators|Administrators]]<ref>Additionally, [[RetroWikipedia:Bureaucrats|bureaucrats]], [[RetroWikipedia:CheckUser|checkusers]], [[RetroWikipedia:Interface administrators|interface administrators]], and [[RetroWikipedia:Oversight|oversighters]] have access, but these groups normally only include administrators.</ref>
* [[RetroWikipedia:Edit filter|Edit filter managers]]
* [[RetroWikipedia:Page mover|Page movers]]
* [[RetroWikipedia:Template editor|Template editors]]

If you are not in one of these groups, you need to submit a request at [[:m:Steward requests/Global permissions#Requests for 2 Factor Auth tester permissions]] to obtain access to 2FA (see [[m:Steward requests/Global permissions/2022-12#Requests_for_2_Factor_Auth_tester_permissions|request examples]]), explicitly mentioning that you have read [[meta:Help:Two-factor authentication|Help:Two-factor authentication on Meta]] (which is '''not''' the page you're reading now). Most users need to request access before they can use 2FA.

Users with advanced rights on other projects, including test wikis hosted by Wikimedia, can also enable 2FA from those projects.

=== Checking whether 2FA is enabled ===
To determine whether your account has 2FA enabled, go to [[Special:Preferences]]. Under "{{int:Prefs-personal}}", check the entry for "Two-factor authentication", which should be between "Global account" and "Global preferences":

* If the entry says "TOTP (one-time token)", 2FA is currently enabled on your account.
* If the entry says "None enabled", 2FA is currently disabled on your account.
* If there is no entry for "Two-factor authentication", your account currently doesn't have access to 2FA, and you'll need to request access at [[:m:Steward requests/Global permissions#Requests for 2 Factor Auth tester permissions]] before you can enable 2FA.

== Enabling 2FA on smartphones and tablet computers ==
{{shortcut|H:ENABLE2FA|H:2FAPHONE|H:2FATABLET}}
[[File:Scanning QR codes on business cards.jpg|thumb|Scanning a [[QR code]] with a smartphone's camera]]
[[File:Aegis Authenticator 3.2 screenshot.png|thumb|Aegis app]]
If you have a [[smartphone]] or [[tablet computer]] with [[Android (operating system)|Android]] or [[iOS]], a mobile app is the most secure and the easiest way to use 2FA. If you don't have a mobile device or if you want to use a [[Microsoft Windows|Windows]] tablet, see "{{pslink|Enabling 2FA on desktop and laptop computers}}".

# Download a 2FA app onto your mobile device. Some options include:
#* '''[https://github.com/beemdevelopment/Aegis Aegis]''' (Android): [[free and open-source]]
#** Android: Download from [https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis Google Play] or [https://f-droid.org/en/packages/com.beemdevelopment.aegis/ F-Droid]
#* '''[https://support.apple.com/en-us/guide/iphone/ipha6173c19f/ios Apple Passwords]''' (iOS)
#* '''[https://github.com/andOTP/andOTP AndOTP]''' (Android): free and open-source (development discontinued<ref>{{cite web |author=((flocke000)) |title=[Unmaintained][App][4.4+][Open source] andOTP - Open source two-factor authentication for Android |url=https://forum.xda-developers.com/t/unmaintained-app-4-4-open-source-andotp-open-source-two-factor-authentication-for-android.3636993/post-87021655 |website=forum.xda-developers.com |access-date=2022-11-09 |date=2022-06-14}}</ref>)
#** Android: Download from [https://play.google.com/store/apps/details?id=org.shadowice.flocke.andotp Google Play]
#* '''[https://mattrubin.me/authenticator/ Authenticator]''' (iOS): free and open-source
#** iOS: Download from the [https://apps.apple.com/us/app/authenticator/id766157276 App Store]
#*[https://ente.io/auth/ '''Ente Auth'''] (Android, iOS): free and open source. Allows viewing (but not adding) 2FA details on web/PC.
#* '''[[FreeOTP]]''' (Android, iOS): free and open-source
#** Android: Download from [https://play.google.com/store/apps/details?id=org.fedorahosted.freeotp Google Play] or [https://f-droid.org/packages/org.fedorahosted.freeotp/index.html.en F-Droid]
#** iOS: Download from the [https://apps.apple.com/us/app/freeotp-authenticator/id872559395 App Store]
#*'''[[Google Authenticator]]'''
#**Android: Download from [https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2 Google Play]
#**iOS: Download from the [https://apps.apple.com/us/app/google-authenticator/id388497605 App Store]
#*'''Microsoft Authenticator'''
#**Android: Download from [https://play.google.com/store/apps/details?id=com.azure.authenticator&hl=en_IN&gl=US Google Play]
#**iOS: Download from the [https://apps.apple.com/us/app/microsoft-authenticator/id983156458 App Store]
#*'''Numberstation'''
#**True Linux on mobile (Mobian, Ubuntu Touch, and [[Mobile operating system#Fully open-source, mixed copyleft and permissive licenses| similar OSes]], but ''not'' Android): Install through your [[package manager]], either in the command terminal, or via [[AppStream]] (if you have it installed) with the button [https://linuxphoneapps.org/apps/org.postmarketos.numberstation/ here].

# Go to [[Special:Manage Two-factor authentication]]. Click "Enable" next to "TOTP (one-time token)", and log in with your username and password.
# The recommended authentication method is to scan a [[QR code]] in the app. In "Step 2" of the setup page, there is a box with a pattern which you have to point your device's camera toward. (Your device might ask you for permission to use the camera first.)
#* If you can't scan the QR code, you can enter the "Two-factor authentication secret key" from "Step 2" of the setup page into the app, which gives you the same result.
# Go back to the 2FA enrollment page. '''Write down the [[#recovery codes|recovery codes]] from "Step 3" and keep them in a secure location.'''
# Type the 6-digit verification code from your app into the 2FA enrollment page under "Step 4".

That's it, you're all set up. '''Now, read "{{pslink|Recovery codes}}".'''

== Enabling 2FA on desktop and laptop computers ==
{{shortcut|H:2FAPC}}
You can use apps like WinAuth, Authenticator, and KeeWeb to handle 2FA tokens on many computers. This is the recommended way to use 2FA if you don't have a smartphone or tablet computer. Certain laptops (like Chromebooks) may need to use the "[[Help:Two-factor_authentication#Enabling_2FA_on_smartphones_and_tablet_computers|tablet]]" section above.

If you currently use a [[password manager]], check whether it supports 2FA. (Your password manager may also refer to 2FA as ''[[One-time password|OTP]]'' or ''[[Time-based One-time Password algorithm|TOTP]]''.) Using your current password manager for 2FA is easier than setting up a new 2FA app.

''Note:'' If you normally edit with your desktop computer, using a desktop 2FA app is slightly less secure than [[#Enabling 2FA on smartphones and tablet computers|using a mobile 2FA app]], as someone with access to both your computer and your password would still be able to log in to your account.

=== WinAuth (Windows) ===
[[File:WinAuth 3 screenshot.png|thumb|WinAuth 2FA app]]
[https://winauth.github.io/winauth/index.html WinAuth] is the recommended 2FA app for [[Microsoft Windows|Windows]] users. It is free and open-source.
# Download [https://winauth.github.io/winauth/index.html WinAuth] onto your Windows PC.
# Go to [[Special:Manage Two-factor authentication]]. Click "Enable" next to "TOTP (one-time token)", and log in with your username and password.
# Click the "Add" button at the bottom-left of Authenticator. Select "Authenticator".
# Type "RetroWikipedia" and your account name (e.g. "RetroWikipedia – Example") into the "Name" field.
# Copy the "Two-factor authentication secret key" from "Step 2" of the setup page and paste it into the "Secret Code" field.
# Leave the next option set to "Time-based".
# Click "Verify authenticator" and then click "OK".
# Optionally set a password for WinAuth. Click "OK".
# Go back to the 2FA enrollment page. '''Write down the [[#Recovery codes|recovery codes]] from "Step 3" and keep them in a secure location.'''
# Type the 6-digit verification code from WinAuth into the 2FA enrollment page under "Step 4". (Click the refresh button in WinAuth to generate another code.)

That's it, you're all set up. '''Now, read "{{pslink|Recovery codes}}".'''

=== Authenticator (Linux) ===
[[File:Authenticator (Linux).png|thumb|Authenticator 2FA app]]
[https://gitlab.gnome.org/World/Authenticator Authenticator] is the recommended 2FA app for [[Linux]] users. It is free and open-source.
# Download [https://gitlab.gnome.org/World/Authenticator Authenticator] onto your Linux computer. (Authenticator requires [[Flatpak]], which is available on all Linux distributions, including [https://flatpak.org/setup/Ubuntu/ Ubuntu].)
# Go to [[Special:Manage Two-factor authentication]]. Click "Enable", and log in with your username and password.
# Click the {{key top|+}} button at the top-left of Authenticator.
# Add the secret 2FA key to Authenticator using either one of these methods:
#* Use Authenticator to take a screenshot of the [[QR code]]:
#*# Click the QR code button at the top-right of Authenticator.
#*# Position your [[Pointer (user interface)|pointer]] before the top-left corner of the QR code from "Step 2" of the 2FA setup page.
#*# Hold down the mouse button, move the pointer to after the bottom-right of the QR code, and then release the mouse button. The form in Authenticator should be automatically filled in.
#* Manually enter the secret key:
#*# Type "RetroWikipedia" into the "Provider" field, and your account name into the "Account Name" field.
#*# Copy the "Two-factor authentication secret key" from "Step 2" of the setup page and paste it into the "2FA Token" field.
# Click "Add" at the top-right of Authenticator.
# Go back to the 2FA enrollment page. '''Write down the [[#Recovery codes|recovery codes]] from "Step 3" and keep them in a secure location.'''
# Type the 6-digit verification code from Authenticator into the 2FA enrollment page under "Step 4".
# Click "Submit".

That's it, you're all set up. '''Now, read "{{pslink|Recovery codes}}".'''

=== KeeWeb (Windows, macOS, Linux, online) ===
[[File:Enabling 2FA on RetroWikipedia with KeeWeb.webm|thumb|Enabling 2FA with KeeWeb]]
[https://keeweb.info/ KeeWeb] is a free and open-source [[password manager]] that also handles 2FA. The app can be downloaded to your computer or used online without installation. KeeWeb refers to 2FA as ''[[one-time password]]s'' (''OTP'').

# Download [https://keeweb.info/ KeeWeb] onto your computer, or open KeeWeb's [https://app.keeweb.info online web app].
# Go to [[Special:Manage Two-factor authentication]]. Click "Enable", and log in with your username and password.
# In KeeWeb, click "New" (the {{key top|+}} icon).
# Add a new entry: Click the {{key top|+}} icon ("Add New") at the top. Then, click "Entry".
# Give the entry a title (e.g. "RetroWikipedia").
# In the right-side pane, click "more...". Then, click "One-time passwords" and click "Enter code manually".
# Copy the "Two-factor authentication secret key" from "Step 2" of the setup page and paste it into the "otp" field in KeeWeb. Press {{keypress|Enter}} on your keyboard.
# Go back to the 2FA enrollment page. '''Write down the [[#Recovery codes|recovery codes]] from "Step 3" and keep them in a secure location.'''
# In KeeWeb, click on "otp" to copy the 6-digit verification code. Paste the code into the 2FA enrollment page under "Step 4".
# Back up your 2FA settings:
#* Click on the {{key top|⚙️}} gear icon ("Settings") at the bottom-right of the KeeWeb window. Click "New" on the left side of the screen.
#* Optionally set a password and a name, and then click "Save to...".
#* Click "File" to save your 2FA settings onto your computer, or choose one of the other options to sync with [[Dropbox (service)|Dropbox]], [[Google Drive]], [[OneDrive]], or [[WebDAV]].

That's it, you're all set up. '''Now, read "{{pslink|Recovery codes}}".'''

== Changing your authentication device ==
For any reason you may want to change your authentication device.  This could be to move your authentications to a replacement computer or mobile device (for example if you buy a new smartphone). There is not currently a ''transfer'' function,<ref>[[phab:T172079]] is open to request a transfer function</ref> however you may accomplish this by [[#Disabling_2FA|turning off 2FA]], and then re-enrolling with your new device. Some applications also support cross-device synchronisation, or allow you to export 2FA details to be imported in another app. 

== Recovery codes ==
{{shortcut|H:SCRATCH}}
{{ombox
| type      = content
| text      = '''Important:''' Store your recovery codes offline in a safe place to ensure that you won't get locked out of your account if your 2FA device fails.
}}

[[File:Scratch codes in RetroWikipedia 2FA enrollment.png|thumb|Example of recovery codes|right]]
When you set up 2FA, you'll be given a number of 16-character recovery codes, each consisting of four alphanumeric blocks. You can [[#Logging in with 2FA|use one of the recovery codes]] if you lose access to your 2FA app (e.g. if your phone or computer gets broken or stolen). ''You only see these codes while setting up 2FA (and never again)'', so copy them from your browser and save them offline in a safe place (e.g. on a [[USB flash drive|memory stick]] or paper printout). '''If you don't keep these codes and encounter a problem with your 2FA device, you will be locked out of your account.'''
* Each recovery code can only be used one time, and it takes two of them to turn off 2FA (the first to log in without 2FA, and the second to shut off 2FA after logging in).
* Don't store these only on your smartphone. If it gets lost you'll lose the codes!
* You still need to follow [[RetroWikipedia:SECURITY|good security practices]]. Don't use your name, date of birth, or anything that can be guessed in a [[dictionary attack]] as a password. Don't write your password down in a place anyone else can see it, and consider whether or not it's a good idea to log in to your RetroWikipedia account on public terminals at schools, libraries, and airports.

If for some reason you need to use one or more recovery codes or feel that they have been compromised, you should generate a new set at your earliest convenience (especially if you are down to three or fewer remaining).

If you are totally locked out, regaining access to your account will be very difficult and usually involve proving your identity beyond the shadow of a doubt to [[:meta:Trust and Safety|Wikimedia Trust and Safety]] via {{email|ca|wikimedia.org}}. If {{abbr|T&S|Trust and Safety}} deny your request, it is ''impossible'' to turn 2FA off and you'll have to create a new account.
{{clear}}

=== Generating new recovery codes ===
{{shortcut|H:REGENSCRATCH}}

To generate a new batch of recovery codes, simply [[H:DISABLE2FA|disable]] and then [[H:ENABLE2FA|re-enable]] two-factor authentication. This will void all of your old recovery codes and create a new batch. Doing this will also void any devices you currently have configured, requiring you to set up the device again, or use a new device.

== Logging in with 2FA ==
===Web interface===
[[File:Logging in with 2FA on RetroWikipedia.png|thumb|Logging in with 2FA via the web interface]]
When you log in, after entering your password, you'll be asked for a verification code.

# Open your 2FA app and you should see a 6-digit verification code.
# Type the verification code in as is (with no spaces), and you should be logged back in
#: Because the verification code is time-based, it may change while you're doing this, in which case you'll have to add the latest code instead. The application will normally indicate when a code is about to expire (e.g. in Google Authenticator, the code's colour changes from blue to red).

If you need to use a [[#Recovery codes|recovery code]], enter it in place of the verification code. Recovery codes are [[case-sensitive]] and need to be entered in [[all caps]]. A recovery code will work either with or without the spaces between the clusters of characters.

===Mobile app===
[[File:RetroWikipedia Mobile App Login 2FA.jpg|thumb|2FA prompt in the mobile app]]
For the iOS and Android versions of the [[H:MOBILEAPP|mobile app]], when prompted for the verification code, you'll need to follow a similar process to the web interface.

If you need to use a recovery code, first choose to use a backup code, and then enter the recovery code. Recovery codes are case-sensitive and must be entered in all caps. The spaces separating the clusters of characters in the recovery code are optional.

=== API access ===
*Most API logon clients such as [[RetroWikipedia:AutoWikiBrowser|AutoWikiBrowser]] and [[RetroWikipedia:Huggle|Huggle]] do not support 2FA, instead users may use a [[Special:BotPasswords|create a "bot password"]] to log on to the API. Please see [[RetroWikipedia:Using AWB with 2FA]] and [[mw:Manual:Huggle/Bot passwords]] for instructions.
*Special client [[mw:API:Login#Example_2:_Process_for_a_wiki_with_special_authentication_extensions|configuration]] to use the API is needed for two-factor authentication.

== Disabling 2FA ==
{{shortcut|H:DISABLE2FA}}
[[File:Disabling 2FA on RetroWikipedia.webm|thumb|left|Disabling 2FA]]
If you no longer want to use 2FA, go to [[Special:Manage Two-factor authentication]] and you'll be given the option to disable it. You'll need to enter a 6-digit verification code, just as you would when logging in. Alternatively enter one of your 16-character recovery codes. After this, 2FA will be turned off on your account.

To change your 2FA app or device, just disable 2FA and then follow the instructions at "{{pslink|Enabling 2FA on smartphones and tablet computers}}" or "{{pslink|Enabling 2FA on desktop and laptop computers}}" to enable it again.
{{clear}}

== Known issues ==
=== Multiple devices ===
Wikimedia's 2FA system is only designed to be used with one device. If you want to use 2FA on multiple devices, you must register all of your devices at the same time. To add 2FA to an additional device:
# Have all of your devices on hand.
# If 2FA is already enabled on your account, [[#Disabling 2FA|disable it]].
# Register all of your devices with the directions at "{{pslink|Enabling 2FA on smartphones and tablet computers}}" and/or "{{pslink|Enabling 2FA on desktop and laptop computers}}", but don't enter the 6-digit verification code into the Two-factor authentication page until all of your devices are registered.

To remove 2FA from a device, simply remove the RetroWikipedia entry from your 2FA app. '''Do not do this unless you have disabled 2FA entirely (see "{{pslink|Disabling 2FA}}") or you have access to 2FA for RetroWikipedia on another device.'''

=== Clock drift ===
If your 2FA device's [[Clock drift|clock becomes too inaccurate]], it will generate the wrong verification codes and you will not be able to log in. To prevent this, the 2FA device's clock should be kept reasonably accurate. Most smartphones and computers keep the clock in sync when they are connected to the Internet, and you will most likely not have to do anything as long as your device is online.

== WebAuthn ==
[[mw:Extension:WebAuthn|WebAuthn]] is another two-factor mechanism that may be enabled; it is currently not recommended as there is [[phab:T244348|no recovery mechanism]] for lost keys and it has less support from community volunteers.  If you use WebAuthn and have a technical issue, you may lose access to your account forever.

WebAuthn may require you to logon on the same project that you have set it up on, when logging on in the future. For example, if you enroll WebAuthn here on the English RetroWikipedia, then log out, you will not be able to log on at the Spanish RetroWikipedia - you would need to log on here first. This is a [[phab:T244088|known issue]].

WebAuthn is not currently supported on the mobile apps (see [[phab:T230043|T230043]]).

== More help ==
* Ask the [[RetroWikipedia:Reference desk/Computing|computing reference desk]] or contact [[:Category:RetroWikipedians willing to assist with two-factor authentication|an editor willing to assist with 2FA]] if you need more help, or if you have any questions.
* If you find something on this page to be incomplete or unclear, please raise the issue on the {{Talk|2=talk page}} and someone will fix it.
* Email {{nospam|info-en|wikimedia.org}} – your ticket will be dealt with by one of the [[WP:OTRS|OTRS]] technical agents.
* Discuss technical issues at the [[RetroWikipedia:VPT|Technical village pump]].
* Join {{IRC|wikipedia-en}} and/or {{IRC|wikipedia-tech}}.
* See also [[:meta:Help:Two-factor authentication|Metawiki help page]] for [[RetroWikipedia:Meta|Meta-Wiki]]'s overview of 2FA.
* There are many OTP clients available (c.f. [[comparison of OTP applications]], see the publisher for application specific assistance.

==Notes==
{{reflist}}

{{RetroWikipedia accounts|collapsed}}