two-factor-authentication.md · cryptotaxi247/CoPilot

Code Commits Issues Pulls Sessions CI/CD

main

md 166 lines 6.37 KB

Rendered Raw

1	---
2	title: Two-Factor Authentication (2FA)
3	description: Enable TOTP-based two-factor authentication on your CoPilot account using an authenticator app.
4	---
5
6	Menu: Profile → Security tab → Two-Factor Authentication
7
8	Best for: All users
9
10	Two-factor authentication (2FA) adds a second verification step every time you log in. After entering your password (or completing SSO), you must also provide a 6-digit code from an authenticator app on your phone or computer.
11
12	CoPilot uses the TOTP (Time-based One-Time Password) standard, which is supported by all major authenticator apps:
13
14	- [Google Authenticator](https://support.google.com/accounts/answer/1066447)
15	- [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app)
16	- [Authy](https://authy.com/)
17	- [1Password](https://1password.com/)
18	- Any TOTP-compatible app
19
20	---
21
22	## Enable 2FA on your account
23
24	<Steps>
25
26	<Step title="Open your profile">
27	Click your username or avatar in the top-right corner and select Profile, then switch to the Security tab.
28	</Step>
29
30	<Step title="Start setup">
31	Click Enable Two-Factor Authentication. CoPilot generates a unique secret and displays a QR code.
32	</Step>
33
34	<Step title="Scan the QR code">
35	Open your authenticator app and scan the QR code displayed on screen.
36
37	> Can't scan? Click Show manual entry key to reveal the secret as a text string. Enter it manually in your authenticator app.
38
39	<Warning>
40	Make sure your device clock is accurate. TOTP codes are time-sensitive and allow only a ±30 second tolerance window. If your clock is off, codes will be rejected.
41	</Warning>
42	</Step>
43
44	<Step title="Verify the code">
45	Enter the 6-digit code currently shown in your authenticator app and click Verify & Enable.
46
47	This confirms that your app is configured correctly and activates 2FA on your account.
48	</Step>
49
50	<Step title="Save your backup codes">
51	After verification, CoPilot displays 8 one-time backup codes. These are your emergency access method if you lose your authenticator device.
52
53	- Click Copy all to copy the codes to your clipboard.
54	- Click Download .txt to save them as a text file.
55	- Store them somewhere safe (e.g. a password manager or a printed sheet in a secure location).
56
57	<Warning>
58	Backup codes are shown only once during setup. If you lose them and lose access to your authenticator app, you will be locked out of your account.
59	</Warning>
60	</Step>
61
62	</Steps>
63
64	---
65
66	## Log in with 2FA
67
68	Once 2FA is enabled, the login flow changes:
69
70	```
71	┌──────────────┐ ┌──────────────┐ ┌──────────────┐
72	│ Enter │────▶│ Enter │────▶│ Session │
73	│ username & │ │ 6-digit │ │ created │
74	│ password │ │ TOTP code │ │ │
75	└──────────────┘ └──────────────┘ └──────────────┘
76	```
77
78	1. Enter your username and password as usual, then click Sign in.
79	2. CoPilot recognizes that your account has 2FA enabled and shows a verification form.
80	3. Open your authenticator app and enter the current 6-digit code, then click Verify.
81	4. You are logged in.
82
83	> SSO + 2FA: If you sign in via SSO (Azure, Google, or Cloudflare Access), you will still be prompted for the TOTP code after the identity provider authenticates you.
84
85	---
86
87	## Use a backup code
88
89	If you cannot access your authenticator app (lost phone, new device, etc.), you can use one of your backup codes instead:
90
91	1. On the 2FA verification screen, click Use a backup code instead.
92	2. Enter one of your saved backup codes (e.g. `ABCD1234EF`).
93	3. Click Use backup code.
94
95	Each backup code can only be used once. After use, it is permanently invalidated.
96
97	---
98
99	## Regenerate backup codes
100
101	If you have used some of your backup codes or suspect they have been compromised:
102
103	1. Go to Profile → Security tab.
104	2. Click Regenerate backup codes.
105	3. Enter your current 6-digit TOTP code to confirm your identity.
106	4. CoPilot generates 8 new backup codes. All previous codes are invalidated immediately.
107	5. Save the new codes (copy or download).
108
109	---
110
111	## Disable 2FA
112
113	1. Go to Profile → Security tab.
114	2. Click Disable 2FA.
115	3. Confirm by entering your current TOTP code or a backup code.
116	4. 2FA is removed from your account. Future logins will only require a password.
117
118	---
119
120	## Brute-force protection
121
122	CoPilot enforces rate limiting on 2FA verification:
123
124	- After 5 failed attempts, your account is locked out of 2FA verification for 15 minutes.
125	- This applies to both TOTP code entry and backup code entry.
126	- The lockout resets automatically after the timeout or on a successful verification.
127
128	---
129
130	## FAQ
131
132	<AccordionGroup>
133
134	<Accordion title="What happens if I lose my phone?">
135	Use one of your backup codes to log in, then either regenerate new backup codes or disable 2FA and set it up again with your new device.
136	</Accordion>
137
138	<Accordion title="Can an admin disable 2FA for a user?">
139	Currently, each user manages their own 2FA. If a user is locked out with no backup codes, an admin can reset their account through the database.
140	</Accordion>
141
142	<Accordion title="Does 2FA apply to API access?">
143	2FA is enforced during interactive login only. API tokens issued after a successful login (including 2FA) remain valid for their normal lifetime.
144	</Accordion>
145
146	<Accordion title="Which authenticator app should I use?">
147	Any TOTP-compatible app works. Popular choices include Google Authenticator, Microsoft Authenticator, Authy, and 1Password. They are all interchangeable — pick whichever you prefer.
148	</Accordion>
149
150	<Accordion title="My codes are always rejected">
151	Check that your device clock is accurate. TOTP codes depend on precise time synchronization (within ±30 seconds). On mobile, enable automatic time in your device settings.
152	</Accordion>
153
154	</AccordionGroup>
155
156	---
157
158	## Environment variables (admin reference)
159
160	\| Variable \| Purpose \| Default \|
161	\|---\|---\|---\|
162	\| `TOTP_ENCRYPTION_KEY` \| Fernet key used to encrypt TOTP secrets at rest in the database. \| Derived from `JWT_SECRET` \|
163
164	<Warning>
165	Once users have enrolled in 2FA, do not change `TOTP_ENCRYPTION_KEY`. Changing it will make all existing TOTP secrets unreadable, locking enrolled users out of 2FA verification.
166	</Warning>