Merge pull request #4 from Web3-Pi/2fa

2fa for cockpit in advanced setup

Author: cmd0s

docs/advanced-setup/2fa.md

@@ -0,0 +1,90 @@
+# Two-Factor Authentication (2FA) for Cockpit
+
+Adding Two-Factor Authentication (2FA) to Cockpit increases the security of your server by requiring a time-based one-time password (TOTP) in addition to your regular credentials.
+
+## Step 1: Install Required Packages
+
+Open a terminal and run:
+
+```sh
+sudo apt-get install libpam-google-authenticator -y
+```
+
+This installs the PAM module for Google Authenticator.
+
+## Step 2: Configure Google Authenticator for Your User
+
+Run the following command to set up Google Authenticator with recommended options:
+
+```sh
+google-authenticator -t -d -f -r 3 -R 30 -W -Q UTF8
+```
+
+!!! note
+
+    - `-t` use TOTP instead of HOTP (recommended).
+    - `-d` disable reuse of previously used TOTP tokens.
+    - `-f` disable confirmation before writing the `~/.google_authenticator` file.
+    - `-r 3 -R 30` limits the number of login attempts to 3 every 30 seconds.
+    - `-W` by default google-authenticator allows the use of codes that were generated a little before or a little after the current time. This option disables that feature (recommended for security).
+    - `-Q UTF8` specifies the encoding for the QR code. Change to `-Q ANSI` if you're having issues with viewing the QR code.
+
+- This will generate a secret key, QR code, and emergency scratch codes.
+- Scan the QR code with your preferred authenticator app (e.g., Google Authenticator, Authy).
+- Enter the verification code from your authenticator app to complete the setup.
+- Save the emergency scratch codes in a safe place. 
+
+!!! note
+
+    Scratch codes are one-time use only. If you lose access to your authenticator app, enter one of these codes to log in and recreate your 2FA setup.
+
+## Step 3: Enable 2FA for Cockpit
+
+Use the following command to add the Google Authenticator PAM module to the Cockpit PAM configuration:
+
+```sh
+sudo bash -c 'echo "auth required pam_google_authenticator.so nullok" >> /etc/pam.d/cockpit'
+```
+
+This tells Cockpit to require a TOTP code during login.
+
+!!! note
+
+    - The `nullok` option disables 2FA for users that do not have a `~/.google_authenticator` file.
+
+## Step 4: Restart Cockpit
+
+Restart the Cockpit service to apply the changes:
+
+```sh
+sudo systemctl restart cockpit
+```
+
+## Step 5: Test Your Setup
+
+1. Log out of Cockpit.
+2. Log back in. You should be prompted for a verification code from your authenticator app.
+
+![Verification Code Prompt](../img/cockpit-verification-code.png)
+
+
+## Uninstalling 2FA
+
+To remove 2FA from Cockpit, simply delete the line you added to the PAM configuration:
+
+```sh
+sudo bash -c 'sed -i "/pam_google_authenticator.so nullok/d" /etc/pam.d/cockpit'
+```
+
+Then restart the Cockpit service:
+
+```sh
+sudo systemctl restart cockpit
+```
+
+You can also remove the generated `~/.google_authenticator` file and the installed packages if you no longer need 2FA:
+
+```sh
+sudo apt remove libpam-google-authenticator -y
+rm ~/.google_authenticator
+```

docs/advanced-setup/index.md

@@ -4,6 +4,7 @@ This section provides advanced setup guides for your Web3 Pi node that aim to op
 
 ## Table of Contents
 
+- [Two-Factor Authentication (2FA)](2fa.md) - Add an extra layer of security to your Cockpit login.
 - [Backup Power](ups.md) - Consider adding a backup power source to your node, in case of power outages.
 - [Power over Ethernet](poe.md) - Use PoE (Power over Ethernet) instead of the included power supply.
 - [Firewall Configuration (UFW)](ufw.md) - Configure UFW to control incoming and outgoing network traffic.

docs/img/cockpit-verification-code.png

@@ -103,6 +103,7 @@ nav:
     - Next Steps: 'setup/next-steps.md'
   - Advanced Setup:
     - 'advanced-setup/index.md'
+    - Two-Factor Authentication (2FA): 'advanced-setup/2fa.md'
     - Backup Power: 'advanced-setup/ups.md'
     - Power over Ethernet: 'advanced-setup/poe.md'
     - Firewall Configuration (UFW): 'advanced-setup/ufw.md'