diff options
Diffstat (limited to 'docs/configuration/system/login.rst')
| -rw-r--r-- | docs/configuration/system/login.rst | 199 |
1 files changed, 167 insertions, 32 deletions
diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 08746201..a5c1b558 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -1,8 +1,10 @@ +:lastproofread: 2022-10-15 + .. _user_management: -############### -User Management -############### +##################### +Login/User Management +##################### The default VyOS user account (`vyos`), as well as newly created user accounts, have all capabilities to configure the system. All accounts have sudo @@ -52,6 +54,8 @@ and paste it. Some terminal emulators may accidentally split this over several lines. Be attentive when you paste it that it only pastes as a single line. The third part is simply an identifier, and is for your own reference. +.. seealso:: SSH :ref:`ssh_operation` + .. cfgcmd:: set system login user <username> authentication public-keys <identifier> key <key> @@ -77,44 +81,154 @@ The third part is simply an identifier, and is for your own reference. .. cfgcmd:: set system login user <username> authentication public-keys <identifier> options <options> - Set the options for this public key. See the ssh ``authorized_keys`` man page - for details of what you can specify here. To place a ``"`` character in the - options field, use ``"``, for example ``from="10.0.0.0/24"`` - to restrict where the user may connect from when using this key. + Set the options for this public key. See the ssh ``authorized_keys`` man + page for details of what you can specify here. To place a ``"`` + character in the options field, use ``"``, for example + ``from="10.0.0.0/24"`` to restrict where the user + may connect from when using this key. -.. cfgcmd:: loadkey <username> <location> +MFA/2FA authentication using OTP (one time passwords) +----------------------------------------------------- - **Deprecation notice:** ``loadkey`` has been deprecated in favour of - :opcmd:`generate public-key-commands` and will be removed in a future - version. See :ref:`ssh`. +It is possible to enhance authentication security by using the :abbr:`2FA +(Two-factor authentication)`/:abbr:`MFA (Multi-factor authentication)` feature +together with :abbr:`OTP (One-Time-Pad)` on VyOS. :abbr:`2FA (Two-factor +authentication)`/:abbr:`MFA (Multi-factor authentication)` is configured +independently per each user. If an OTP key is configured for a user, 2FA/MFA +is automatically enabled for that particular user. If a user does not have an +OTP key configured, there is no 2FA/MFA check for that user. - SSH keys can not only be specified on the command-line but also loaded for - a given user with `<username>` from a file pointed to by `<location>.` Keys - can be either loaded from local filesystem or any given remote location - using one of the following :abbr:`URIs (Uniform Resource Identifier)`: +.. cfgcmd:: set system login user <username> authentication otp key <key> - * ``<file>`` - Load from file on local filesystem path - * ``scp://<user>@<host>:/<file>`` - Load via SCP from remote machine - * ``sftp://<user>@<host>/<file>`` - Load via SFTP from remote machine - * ``ftp://<user>@<host>/<file>`` - Load via FTP from remote machine - * ``http://<host>/<file>`` - Load via HTTP from remote machine - * ``tftp://<host>/<file>`` - Load via TFTP from remote machine + Enable OTP 2FA for user `username` with default settings, using the BASE32 + encoded 2FA/MFA key specified by `<key>`. -Example -------- +Optional/default settings +^^^^^^^^^^^^^^^^^^^^^^^^^ -In the following example, both `User1` and `User2` will be able to SSH into -VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only -be able to connect from a single IP address. +.. cfgcmd:: set system login user <username> authentication otp rate-limit <limit> + :defaultvalue: + + Limit logins to `<limit>` per every ``rate-time`` seconds. Rate limit + must be between 1 and 10 attempts. + +.. cfgcmd:: set system login user <username> authentication otp rate-time <seconds> + :defaultvalue: + + Limit logins to ``rate-limit`` attemps per every `<seconds>`. Rate time must + be between 15 and 600 seconds. + +.. cfgcmd:: set system login user <username> authentication otp window-size <size> + :defaultvalue: + + Set window of concurrently valid codes. + + By default, a new token is generated every 30 seconds by the mobile + application. In order to compensate for possible time-skew between + the client and the server, an extra token before and after the current + time is allowed. This allows for a time skew of up to 30 seconds + between authentication server and client. + + For example, if problems with poor time synchronization are experienced, + the window can be increased from its default size of 3 permitted codes + (one previous code, the current code, the next code) to 17 permitted codes + (the 8 previous codes, the current code, and the 8 next codes). This will + permit for a time skew of up to 4 minutes between client and server. + + The window size must be between 1 and 21. + +OTP-key generation +^^^^^^^^^^^^^^^^^^ + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +.. cfgcmd:: generate system login username <username> otp-key hotp-time + rate-limit <1-10> rate-time <15-600> window-size <1-21> + +An example of key generation: .. code-block:: none - set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" - set system login user vyos authentication public-keys 'User1' type ssh-rsa - set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" - set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" - set system login user vyos authentication public-keys 'User2' type ssh-rsa + vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 + # You can share it with the user, he just needs to scan the QR in his OTP app + # username: otptester + # OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY + # OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 + █████████████████████████████████████████████ + █████████████████████████████████████████████ + ████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ + ████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ + ████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ + ████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ + ████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ + ████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ + █████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ + ████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ + ████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ + ████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ + ████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ + ████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ + ████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ + ████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ + ████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ + ████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ + ████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ + ████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ + ████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ + █████████████████████████████████████████████ + █████████████████████████████████████████████ + # To add this OTP key to configuration, run the following commands: + set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' + set system login user otptester authentication otp rate-limit '2' + set system login user otptester authentication otp rate-time '20' + set system login user otptester authentication otp window-size '5' + +Display OTP key for user +^^^^^^^^^^^^^^^^^^^^^^^^ + +To display the configured OTP user key, use the command: + +.. cfgcmd:: sh system login authentication user <username> otp + <full|key-b32|qrcode|uri> + +An example: + +.. code-block:: none + vyos@vyos:~$ sh system login authentication user otptester otp full + # You can share it with the user, he just needs to scan the QR in his OTP app + # username: otptester + # OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY + # OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 + █████████████████████████████████████████████ + █████████████████████████████████████████████ + ████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ + ████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ + ████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ + ████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ + ████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ + ████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ + █████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ + ████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ + ████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ + ████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ + ████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ + ████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ + ████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ + ████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ + ████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ + ████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ + ████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ + ████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ + ████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ + █████████████████████████████████████████████ + █████████████████████████████████████████████ + # To add this OTP key to configuration, run the following commands: + set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' + set system login user otptester authentication otp rate-limit '2' + set system login user otptester authentication otp rate-time '20' + set system login user otptester authentication otp window-size '5' RADIUS ====== @@ -158,7 +272,6 @@ Configuration the attribute you will only get regular, non privilegued, system users. - Login Banner ============ @@ -176,3 +289,25 @@ information for this system. .. note:: To create a new line in your login message you need to escape the new line character by using ``\\n``. + + +Example +======= + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the ``vyos`` user a 2FA/MFA keycode is required in addition to +the password. + +.. code-block:: none + + set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" + set system login user vyos authentication public-keys 'User1' type ssh-rsa + set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" + + set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" + set system login user vyos authentication public-keys 'User2' type ssh-rsa + + set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 + set system login user vyos authentication plaintext-password vyos |