2fa

docs/guides/teams.md

@@ -78,18 +78,19 @@ You will now have access to the organizer account and associated events as speci
 If you have been invited to a team and you already have a personal pretix account, you can log in to pretix. 
 You will now have access to the organizer account and associated events as specified by the person who invited you. 
 
-### Two-factor authentication (2FA) 
+### Requiring two-factor authentication (2FA) 
 
-You can enable two-factor authentication by clicking your name in the top right corner of the website, which takes you to a page titled "Account settings". 
-Next to "Two-factor authentication", click :btn:Enable:. 
-You will then be asked to add a device: a smartphone with Google Authenticator or a comparable application, or a WebAuthn-compatible hardware token such as a Yubikey. 
-Provide a "Device name", choose the "Device type", and click :btn:Continue:. 
+You can require all members of a team to use two-factor authentication (2FA). 
+In order to do so, create or edit the team. 
+Check the box next to "Require all members of this team to use two-factor authentication". 
+This setting may take a few minutes to take effect. 
 
-If you choose your smartphone as an authentication device, you have to open the authenticator app on your smartphone and scan the QR code displayed in the pretix backend. 
-If you choose a WebAthn-compatible hardware token, your browser will prompt you to touch it. 
-In either case, the box next to "Require second factor for future logins" will be checked by default, meaning that you have to have this device on hand every time you want to log in ot pretix now. 
+When a member of that team who has not enabled 2FA next logs in, they will be redirected to the page titled "Two-factor authentication". 
+They cannot leave that page until they enable 2FA (and add a device if necessary), or leave the team in question. 
 
-While creating or editing a team, you can check the box next to "Require all members of this team to use two-factor authentication". 
-This setting may take a few minutes to take effect. 
-The next time a member of that team who has not enabled 2FA logs in, they will be taken to the page titled "Two-factor authentication". 
-They cannot leave that page until they enable 2FA (and add a device if necessary), or leave the team in question. 
+In order to learn more about the advantages of 2FA and how to set it up for in your pretix user account, read our article on [Two-factor authentication](two-factor-authentication.md). 
+
+### Setting up 2FA as required
+
+If pretix takes you directly to the page titled "Two-factor authentication" and you open any other page in pretix, then the person managing your team has [required 2FA](#requiring-two-factor-authentication-2fa) for your team. 
+In order to set up 2FA for your account, read our article on [Two-factor authentication](two-factor-authentication.md). 

docs/guides/two-factor-authentication.md

@@ -0,0 +1,182 @@
+# Two-factor authentication 
+
+By default, your pretix account is secured with a single factor: your password. 
+You can add a second factor to improve security. 
+This is called "two-factor authentication" or **2FA**. 
+
+The second security factor can be a WebAuthn-compatible hardware token or an authenticator application. 
+This article explains the advantages of 2FA and how to set it up for your pretix user account. 
+
+## Background information 
+
+Depending on your usage of pretix and permission settings, your user account can grant access to a lot of sensitive information. 
+This sensitive information can include, for example, company secrets, payment history, and your customers' data. 
+
+A strong password offers a good baseline level of security. 
+But potential malicious actors can breach passwords through malware, social engineering, and other methods. 
+
+A second factor for authentication makes such an attack significantly more difficult. 
+An attacker would have to gain access to both your 2FA device and your account credentials. 
+Detecting a breach of one security factor can give you enough time to change it before the attacker can also breach the other factor. 
+
+You should establish a policy regarding the use of 2FA in your organization. 
+This policy should include a list of approved hardware tokens and apps for 2FA. 
+It should contain a protocol on how to store emergency tokens. 
+This policy should be documented and communicated to all staff members. 
+
+Put such a policy into place or review your existing policy for the points mentioned above. 
+This is a prerequisite for using 2FA with pretix. 
+
+We recommend setting up 2FA for all user accounts within your organization. 
+The information security standard ISO27001 requires secure authentication and recommends 2FA. 
+If you want to require your coworkers to use 2FA for their pretix accounts, refer to the article on [Teams](teams.md#requiring-two-factor-authentication-2fa). 
+Once everyone on your team has done so, a malicious attack is very unlikely to succeed. 
+
+## Prerequisites
+
+!!! Note 
+    The applications and devices listed here are **examples**. 
+    They are not recommendations. 
+    We recommend doing some research into trustworthy hardware tokens or authenticator apps. 
+    Do this before deciding on a 2FA solution for your team. 
+
+Depending on the authentication method you intend to use, you need to have: 
+
+ - a WebAuthn-compatible hardware token such as a YubiKey **or** 
+ - an authenticator app capable of generating time-based one-time passwords (TOTP), such as Microsoft Authenticator, Google Authenticator, Bitwarden, or FreeOTP. 
+
+## How to
+
+Log in to your pretix user account. 
+Click the :btn-icon:fa3-user:[Your name]: button in the top right corner. 
+This takes you to your user account settings. 
+
+!["Page titled 'Account settings', displaying settings for 'Full name', 'Language', 'Default timezone', 'Notifications', 'Email', 'Password', 'Two-factor authentication', 'Authorized applications', and 'Account history'."](../assets/screens/account/account-settings.png "Account settings")
+
+You should store your **emergency tokens** securely outside of pretix before setting up 2FA. 
+You can use these codes in place of your 2FA device in case you lose access to it. 
+Copy the codes and print them or write them down on paper. 
+Store that paper in a safe place such as a locked drawer. 
+
+Alternatively, you can store the emergency tokens digitally in an encrypted file or in a password manager. 
+**Do not** store them in the same password manager or database that also contains your account password. 
+
+!!! Note 
+    Ensure that you have stored your emergency tokens outside of pretix and that you know where to find them. 
+    You need these tokens in case you lose access to your 2FA device. 
+
+Take a look at the "Two-factor authentication" setting. 
+If 2FA is disabled, then there is a gray "Disabled" tag next to it. 
+In order to enable 2FA, click the :btn:Enable: button. 
+
+!["Page titled 'Two-factor authentication', displaying the 'Two factor status' as 'currently disabled', a button for adding a new registered device, and emergency tokens."](../assets/screens/account/two-factor-authentication.png "Two-factor authentication")
+
+On the next page, click the :btn-icon:fa3-plus:Add a new device: button. 
+Enter a name. 
+The next steps are different depending on whether you want to use [a TOTP app](#using-a-totp-app) or a [hardware token](#using-a-hardware-token). 
+
+!!! Note 
+    Once you have set up 2FA, losing access to the device for 2FA means also losing access to your pretix user account. 
+    In order to prevent such a situation, you can add multiple devices. 
+
+    However, every additional method for logging in to your account offers potential attackers an additional point of entry. 
+    In order to maximize security, only add a single device for 2FA. 
+
+The advantage of a TOTP app is that you probably already have a device on hand which you can use for TOTP. 
+This can be your work phone, your personal phone, another mobile device, or a separate computer. 
+If this is the case, then you can use the device you already have on hand for 2FA. 
+
+If you use separate applications for password storage and TOTP generation, then the TOTP method offers good security. 
+However, like any software run on a device connected to the internet, a TOTP app is vulnerable to malware. 
+
+A hardware token is much cheaper than a smartphone. 
+If you need to buy a new device for 2FA, then this can be an advantage. 
+Another advantage is that hardware tokens are less susceptible to software attacks. 
+
+You must remove your hardware token from the computer and store it in a safe place or keep it on your person whenever you are not actively using it. 
+Treat it like your personal keychain. 
+One downside of hardware tokens is that they are typically smaller than a phone and only used for authentication purposes. 
+Thus, they can be easier to lose. 
+
+### Using a TOTP app 
+
+Under "Device type", select `Smartphone with the Authenticator application`. 
+Then, click the :btn:Continue: button. 
+
+!["Page titled 'Add a two-factor authentication device', instructing you to download an authenticator app, scan a QR code, alternatively enter a code in the app, and then enter the code from the app in the pretix backend."](../assets/screens/account/add-device.png "Add a two-factor authentication device—App")
+
+Open your TOTP app. 
+Create a new entry for the TOTP secret. 
+Scan the QR code that the pretix backend is displaying. 
+Alternatively, click :btn:Can't scan the barcode?: and enter the code displayed under `3`. 
+
+!!! Note 
+    **Do not** store your password and your TOTP secret in the same password manager. 
+    If it is possible to access both factors through the same primary password, then the second factor only offers very little additional security compared to single-factor authentication. 
+
+    For instance, **do not** add the TOTP secret to the same password manager entry as your pretix user account data. 
+    Use separate apps for TOTP generation and password storage, or at least separate databases. 
+
+Save the entry in your TOTP app. 
+It should now display a six-digit code that changes every 30 seconds. 
+This code is the time-based one-time password. 
+Enter it in the pretix backend in the field labeled "Enter the displayed code here". 
+Then, click the :btn:Continue: button. 
+
+This takes you back to the page titled "Two-factor authentication". 
+The page will now state that 2FA is enabled and under "Registered devices", it will list the device running the TOTP app. 
+
+From now on, you will need both your password and the TOTP from your app to log in to your pretix user account. 
+
+### Using a hardware token 
+
+Connect the hardware token to your computer. 
+Under "Device type", select `WebAuthn-compatible hardware token (e.g. Yubikey)`. 
+Then, click the :btn:Continue: button. 
+
+!["Page titled 'Add a two-factor authentication device', instructing you to connect a WebAuthn device."](../assets/screens/account/add-device-webauthn.png "Add a two-factor authentication device—Hardware")
+
+A new page will open and your browser will prompt you to activate your hardware token. 
+Activate it. 
+For instance, if you are using a YubiKey, touch the blinking capacitive button. 
+
+This takes you back to the page titled "Two-factor authentication". 
+The page will now state that 2FA is enabled and under "Registered devices", it will list the hardware token. 
+
+From now on, you will need both your password and the hardware token to log in to your pretix user account. 
+
+## Troubleshooting 
+
+### You have lost access to your 2FA device
+
+If you have lost access to your 2FA device because it is broken, stolen, or lost, then you should take the following steps: 
+
+ - use one of your emergency tokens to log in 
+ - remove the 2FA device from your user account 
+ - acquire a replacement for the lost 2FA device 
+ - add that device to your account 
+
+In order to do so, open the [login page](https://pretix.eu/control/login). 
+Enter your email address and password. 
+When the page prompts you to touch your hardware key or enter the TOTP, enter one of the emergency tokens instead. 
+Then, click the :btn:Continue: button. 
+
+You can only use each emergency token once. 
+Delete it from the list or cross it out after you have used it. 
+
+Click the :btn-icon:fa3-user:[Your name]: button in the top right corner. 
+This takes you to your user account settings. 
+Click :btn:Change two-factor settings:. 
+Seek out the lost device in the list and click the :btn:Remove: button next to it. 
+If this is the only connected 2FA device, then this action will disable 2FA for your account. 
+
+Acquire a replacement for the lost 2FA device. 
+Add that device to your account as described under [How to](#how-to). 
+
+### You have lost access to your 2FA device and to the emergency tokens 
+
+If you have lost access to your 2FA device and to the emergency tokens, you should contact our support via [email](mailto:support@pretix.eu) or [phone](tel:+4962213217750). 
+
+## See also 
+
+If you want to require your coworkers to use 2FA for their pretix accounts, refer to the article on [Teams](teams.md#requiring-two-factor-authentication-2fa).