One-time password authentication with PAM

This guide explains how to use pam_oath to set up the usage of one-time passwords (OTPs) to authenticate on a system. Any service using PAM for authentication (such as ssh) can use this method.

Note that the clock of the system running the service and the one providing the one-time password must be synchronised.

• apt install libpam-oath to install the needed modules
• (Optional) apt install qrencode to generate QR codes of the OTP keys for an easy installation in OTP applications
• Create a file in which to store user keys: touch {users file (e.g. /etc/pam.d/sshd.users.oath)}
• chmod 600 {users file}
• Configure the service(s) for which you want to use this authentication

SSH configuration

In order OTP during password authentication for ssh connections, do the following. Note that authentication using a ssh key will not be affected.

• Edit /etc/pam.d/sshd, adding a line auth {sufficient or required} pam_oath.so usersfile={users file} window={window} digits={nb digits}, where:
  • The position of the line w.r.t. other auth options determines at which step in the authentication process the OTP is asked
    • Some could be hidden inside @include common-auth
  • {sufficient or required}: sufficient: giving a good OTP suffices for authentication. Required: a OTP is always required to authenticate (even if another method was given, such as a password)
    • It is better to set it to sufficient first for testing, placing the authentication method first in the file, and set it to required only after having verified that it works and users can connect
  • {users file (e.g. /etc/pam.d/sshd.users.oath)}: the file created when setting up pam_oath. This is where OTP keys for each user must be set.
  • {window (e.g. 30)}: how many seconds will each OTP be valid for. This setting should be copied in the OTP application that you use to generate the codes. Must be smaller than 60.
  • {nb digits (e.g. 6)}: how many digits in one OTP code
• Create or edit /etc/ssh/sshd_config.d/custom.conf (or /etc/ssh/sshd_config):
  • Set ChallengeResponseAuthentication to yes
  • Set UsePAM to yes
• systemctl reload ssh

Key generation

In order for a user to be able to use OTP authentication, an entry for them must be set in the users file, with an initial key which must be copied to the application used to generate OTPs.

• Run ./otp_make_key.sh which will:
  • Generate a random key
  • Print an entry to be added in the users file, similar to HOTP/T{window}/{nb digits} {user name} - {key}
  • Convert the key to base 32, since many OTP applications use the key in this format
  • Create a QR code for an easy set up in OTP applications such as FreeOTP+