Configuration of sshd
Multifactor authentication (MFA) can be implemented with the help of OpenPAM. The Google Authenticator is currently provided as an OpenPAM module (PAM module for short) for this purpose. In particular, this implements time-based one-time passwords (TOTP) according to RFC 6238.
To use OpenPAM for SSH server authentication, some changes in the sshd configuration file are required. First, PAM authentication must be enabled by setting the UsePAM option to "yes".
To really address OpenPAM, changes/additions to the AuthenticationMethods option are necessary. In addition to the known option values "password" and "publickey", the option value "keyboard-interactive" can now also be used, which authenticates using OpenPAM. In contrast to OpenSSH implementations in the open world, with the "password" option value the authentication is always performed by OpenSSH itself and not by OpenPAM.
OpenPAM Configuration
PAM stands for Pluggable Authentication Module. It is a flexibly configurable and extensible method for authentication in Unix-like operating systems.
OpenPAM is an implementation of the PAM mechanism from the open world. OpenPAM allows the integration of different authentication methods based on the requirements of the organization. This may involve the use of username and password in conjunction with one-time passwords to achieve multifactor authentication. It is also conceivable to collect logging or accounting information through PAM modules to be created accordingly.
The OpenPAM configuration is done in the file /etc/pam.conf or in a configuration file below /etc/pam.d/*. Different PAM modules can be used for different authentication steps, e.g., pam_unix for password authentication (on the same basis as the OpenSSH server's "password" authentication), pam_google_authenticator for one-time password-based authentication, etc.
Authentication Steps
When the OpenSSH server performs authentication of the user according to the AuthenticationMethods option settings, the following steps are performed:
- The authentication operations behind the "password" and "publickey" option values are performed by the OpenSSH Server itself, as before.
- For the "keyboard-interactive" option value, the OpenSSH server sends a request to OpenPAM.
- OpenPAM checks its configuration and determines which PAM modules should be used for authentication. These are called in turn until the authentication result is final, which is then sent back to the OpenSSH server by OpenPAM.
OpenPAM Configuration File
The OpenPAM configuration file, pam.conf, is located in the /etc directory, just like the OpenSSH configuration files. It specifies which PAM modules should be used for certain authentication steps. Each entry in the configuration file corresponds to a PAM module and describes when and how it should be used. If necessary, the subsequent PAM modules are still called or not because the result of the module already uniquely determines the overall result.
Syntax
The configuration file consists of lines, where each line represents a PAM module entry unless it is a comment line starting with '#'. The syntax is as follows:
[ServiceName] [Type] ControlFlag ModulePath [ModuleOptions]
ServiceName: The name of the service or application to which the configuration applies.
Type: Specifies the purpose for which a PAM module should be used.
ControlFlag: A control flag that governs the behavior of the PAM module
ModulePath: The relative or absolute file path of the PAM module to use (relative to /opt/TCP-IP-SV/openssh/lib, /usr/lib, or /usr/local/lib).
ModuleOptions: Optional parameters or configuration options for the PAM module.
Type
account: Manages non-authentication account management.
auth: Authenticates users and grants privileges.
password: Updates user authentication tokens.
session: Performs actions before/after user sessions.
ControlFlag
required: Failure results in overall failure.
requisite: Failure terminates OpenPAM processing.
sufficient: Success terminates OpenPAM processing.
optional: Relevant only if it's the sole PAM module used.
Examples
PAM Configuration with Password
In this example, the pam_unix module is used for password authentication in an SSH login.
sshd_config:
AuthenticationMethods keyboard-interactive
pam.conf:
sshd account optional pam_unix.so sshd password optional pam_unix.so sshd session optional pam_unix.so sshd auth required pam_unix.so
PAM Configuration with Password and Token
Here, the pam_google_authenticator module is added for two-factor authentication. This example also demonstrates the use of multiple PAM modules for different authentication steps.
sshd_config:
AuthenticationMethods keyboard-interactive
pam.conf:
sshd account optional pam_unix.so sshd password required pam_unix.so sshd session optional pam_unix.so sshd auth required pam_unix.so sshd auth required pam_google_authenticator.so
PAM Configuration with Public Key and Token
To use public keys together with OpenPAM, the sshd configuration needs adjustment.
sshd_config:
AuthenticationMethods publickey,keyboard-interactive
pam.conf:
sshd account optional pam_unix.so sshd password required pam_unix.so sshd session optional pam_unix.so sshd auth required pam_google_authenticator.so
PAM Configuration with Public Key / Password and Token
In this example, either a public key or a password can be used.
sshd_config:
AuthenticationMethods keyboard-interactive,publickey keyboard-interactive,password
pam.conf:
sshd account optional pam_unix.so sshd password required pam_unix.so sshd session optional pam_unix.so sshd auth required pam_google_authenticator.so
PAM Configuration with Public Key, Password, and Token (3-Factor Authentication)
This is an extreme example to show all possible authentication steps.
sshd_config:
AuthenticationMethods publickey,password,keyboard-interactive
pam.conf:
sshd account optional pam_unix.so sshd password required pam_unix.so sshd session optional pam_unix.so sshd auth required pam_google_authenticator.so
In the following variant, the user password is requested by the PAM module pam_unix, but there should be no difference in the result.
sshd_config:
AuthenticationMethods publickey,keyboard-interactive
pam.conf:
sshd account optional pam_unix.so sshd password required pam_unix.so sshd session optional pam_unix.so sshd auth required pam_unix.so sshd auth required pam_google_authenticator.so
Notes
- The order of PAM modules in the configuration file is important. They are processed in the specified order.
- The used PAM modules must be present on the system and correctly configured.
- Consult the documentation of individual PAM modules for their specific configuration options.
This example highlights the fundamental functionality and configuration of the OpenPAM configuration file. For more detailed information about advanced configuration options we recommend referring to the official OpenPAM documentation in /opt/TCP-IP-SV/openssh/readme/TCP-IP-SV.openssh (text/pam.conf.5.txt or the corresponding file in html/ or pdf/).
Unix PAM Module
The pam_unix module is responsible for authentication using a password. It offers additional configuration options via the ModuleOptions in the pam.conf.
Setting up the PAM module
- nullok: Allows users to log in with an empty password.
Google Authenticator PAM Module
The HMAC-based One-Time Password (HOTP) is specified in RFC 4226, and the Time-Based One-Time Password (TOTP) is specified in RFC 6238.
Setting Up the PAM Module
The Google Authenticator PAM module offers additional configuration options, which can be set via ModuleOptions in pam.conf.
- authtok_prompt=<prompt>: Overrides the default prompt text (for sentences with spaces, the entire option must be enclosed in square brackets).
- debug: Enable more verbose log messages in the syslog.
- noskewadj: Disables time tolerance for token comparison.
- no_increment_hotp: Do not increment the counter for failed HOTP attempts. If HOTP is used, this option is necessary to avoid user exclusion by brute force.
- nullok: Allow users to log in without OTP if no OTP has been set up yet.
- echo_verification_code: Displays the 2FA token when it is entered in the terminal.
- grace_period=<seconds>: If present and non-zero, a period can be specified in which no second verification code is requested (comparison of IP and timestamp).
User Setup Procedure
- Execute the executable file "google-authenticator" to generate a new secret key in your user directory. Configuration settings will be stored under ~/.google_authenticator.
- Upon each login to your system, you will now be prompted to enter your TOTP code (Time-Based One-Time Password) or HOTP code (counter-based One-Time Password), depending on the options passed to "google-authenticator."
- During the initial rollout process, not all users might have created a 2FA key. To enable 2FA, nonetheless, the nullok option is required.
pam.conf:
sshd auth required pam_google_authenticator.so nullok