2fa

docs/api.md

@@ -4,11 +4,14 @@ This document describes the PiKVM API. Since the system consists of microservice
 
 
 -----
-## Authorization
+## Authentication
 
-All APIs are restricted to authorization. To make requests, you either need to authorize each request individually,
+All APIs are restricted to authentication. To make requests, you either need to auth each request individually,
 or get a token and pass it as a cookie with each request.
 
+!!! note
+    With enabled [2FA](auth), you will need to add the one-time code to the password without spaces. That is, if the password is `foobar` and the code is `123456`, then you need to use `foobar123456` as the password.
+
 
 ### Single request auth
 
@@ -29,7 +32,7 @@ There are two options here:
 
 ### Session-based cookie auth
 
-1. Authorize and get token for the user using `POST /api/auth/login`:
+1. Get the access token for the user using `POST /api/auth/login`:
 
     ```
     $ curl -k -v -X POST --data user=admin --data passwd=admin https://pikvm/api/auth/login

docs/auth.md

@@ -0,0 +1,65 @@
+# Authentication
+
+PiKVM comes with the following default passwords:
+
+* **Linux admin** (SSH, console, etc.): user `root`, password `root`.
+* **PiKVM Web Interface, API, VNC...**: user `admin`, password `admin`.
+
+**These are two separate entities with independent accounts.** To change passwords, you will need to use the terminal access via SSH or Web Terminal. If you are using the Web Terminal, use the `su -` command to get root access (enter the root user password).
+
+
+## Linux authentication
+
+```
+# rw
+# passwd root
+# ro
+```
+
+## KVM authentication
+
+```
+# rw
+# kvmd-htpasswd set admin
+# ro
+```
+
+Please note that admin is the default user. It is possible to create several different users
+with different passwords to access the Web UI, but keep in mind that they all have the same rights:
+
+```
+# kvmd-htpasswd set <user> # Sets a new user with password
+# kvmd-htpasswd del <user> # Removes/deletes a user
+```
+
+
+## Two-factor authentication
+
+This is a new method of strengthening the protection of PiKVM, available since `KVM >= 3.196`.
+It is strongly recommended to enable it if you expose the PiKVM in the big and scary Internet.
+
+!!! warning
+    Using 2FA eliminates the possibility of using [IPMI](ipmi) and [VNC with vncauth](vnc) (not used by default).
+    It also slightly affects the use of API and regular VNC with user/password, read below.
+
+Steb-by step to enable 2FA:
+
+1. Update OS: `rw && pacman -Syu && reboot`.
+
+2. **Make sure that NTP is running otherwise you will not be able to access** (`timedatectl` command).
+
+3. Install **Google Authenticator** app to your phone ([iOS](https://apps.apple.com/us/app/google-authenticator/id388497605), [Android](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2)). It will generate one-time access codes.
+
+4. Configure one-time codes on PiKVM:
+   ```
+   rw
+   kvmd-totp init
+   ro
+   ```
+
+5. Run **Google Authenticator** and scan the QR code.
+
+6. Now, on the PiKVM login page, you will need to add 6 digits to the **2FA code** field.
+
+!!! note
+    With 2FA for API or VNC authentication, you will need to add the one-time code to the password without spaces. That is, if the password is `foobar` and the code is `123456`, then you need to use `foobar123456` as the password.

docs/first_steps.md

@@ -92,12 +92,14 @@ For future examples, let's assume that your PiKVM has received the address **192
     # kvmd-htpasswd set admin
     # ro
     ```
-    If you require additional user changes you can use the following:
+    If you require additional user for the Web UI access, use the following:
     ```
-    # kvmd-htpasswd set <user> # Sets a new user
+    # kvmd-htpasswd set <user> # Sets a new user with password
     # kvmd-htpasswd del <user> # Removes/deletes a user
     ```
 
+    Optionally you can enable the [two-factor athentication](auth).
+
 ## Configuring PiKVM
 
 Most of the PiKVM settings are done through configuration files. All configuration changes must be made from under the `root` user (that is, the administrator).

docs/ipmi.md

@@ -10,7 +10,7 @@ IPMI is an [old protocol](https://en.wikipedia.org/wiki/Intelligent_Platform_Man
 It can be useful for managing a large number of machines with PiKVM. Its advantage is that it is supported by many enterprise systems.
 
 !!! warning
-    Although PiKVM supports the IPMI protocol, we strongly recommend that you **DO NOT USE IT** outside of trusted networks due to the protocol's [insecurity](https://github.com/NitescuLucian/nliplace.com.blog.drafts). Use Redfish or [KVMD API](api.md) instead of it.
+    Although PiKVM supports the IPMI protocol, we strongly recommend that you **DO NOT USE IT** outside of trusted networks due to the protocol's [insecurity](https://github.com/NitescuLucian/nliplace.com.blog.drafts). Use Redfish or [KVMD API](api.md) instead of it. Also IPMI can not work with [2FA](auth).
 
 To enable IPMI BMC follow these steps:
 

docs/vnc.md

@@ -42,6 +42,9 @@ As an alternative to the web interface, you can use VNC with various desktop cli
 
 5. Switch filesystem back to read-only: `ro`.
 
+!!! note
+    With enabled [2FA](auth), you will need to add the one-time code to the password without spaces. That is, if the password is `foobar` and the code is `123456`, then you need to use `foobar123456` as the password. Also note that `vncauth` (step 3) will not work with 2FA.
+
 
 ## Configuring the client
 

mkdocs.yml

@@ -62,6 +62,7 @@ nav:
     - "Getting started":
         - "PiKVM v3 HAT guide": v3.md
         - "First steps": first_steps.md
+        - "Authentication": auth.md
         - "FAQ": faq.md
     - "Networking":
         - "Internet access":