From 2c7cf7cc02050d4b40e0cdf17a5cf24ca11f2c78 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Mon, 23 Jan 2023 14:44:49 +0200 Subject: [PATCH] 2fa --- docs/api.md | 9 ++++--- docs/auth.md | 65 +++++++++++++++++++++++++++++++++++++++++++++ docs/first_steps.md | 6 +++-- docs/ipmi.md | 2 +- docs/vnc.md | 3 +++ mkdocs.yml | 1 + 6 files changed, 80 insertions(+), 6 deletions(-) create mode 100644 docs/auth.md diff --git a/docs/api.md b/docs/api.md index 93cbebb4..8eadf6ce 100644 --- a/docs/api.md +++ b/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 diff --git a/docs/auth.md b/docs/auth.md new file mode 100644 index 00000000..40bb4ba5 --- /dev/null +++ b/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 # Sets a new user with password +# kvmd-htpasswd del # 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. diff --git a/docs/first_steps.md b/docs/first_steps.md index 4d0bb232..63cc3a70 100644 --- a/docs/first_steps.md +++ b/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 # Sets a new user + # kvmd-htpasswd set # Sets a new user with password # kvmd-htpasswd del # 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). diff --git a/docs/ipmi.md b/docs/ipmi.md index 21553d1e..e5fcc353 100644 --- a/docs/ipmi.md +++ b/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: diff --git a/docs/vnc.md b/docs/vnc.md index 885bc7b5..bf277ceb 100644 --- a/docs/vnc.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 644c7a50..4b0385cc 100644 --- a/mkdocs.yml +++ b/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":