PAM_GOOGLE_AUTHENTICATOR(8)

💖 PAM_GOOGLE_AUTHENTICATOR 💖

okay bestie, welcome to pam_google_authenticator(8), the section-8 manual page for the Google Authenticator PAM module. it's the lil guy that gives your login a second factor, and honestly? iconic. let's get into it 🫶

✨ NAME ✨

pam_google_authenticator — the PAM module for Google two-factor authentication. two factors, one module, zero chill. 💅

🌸 SYNOPSIS 🌸

pam_google_authenticator.so [secret=file] [authtok_prompt=prompt]
[user=username] [no_strict_owner] [allowed_perm=0nnn] [debug]
[try_first_pass|use_first_pass|forward_pass] [noskewadj] [no_increment_hotp] [nullok] [echo_verification_code]

🦋 DESCRIPTION 🦋

so the pam_google_authenticator module is literally designed to protect user authentication with a second factor — either time-based (TOTP) or counter-based (HOTP). before you log in, the user gets asked for BOTH their password and a one-time code. no skipping steps, no sneaking in 🙈

those one-time codes can be generated with the Google Authenticator application, installed on the user's Android device. and to generate + verify those codes, a secret key (randomly generated, no cap) has to be shared between the device that makes the one-time codes and the system where this PAM module is enabled. it's giving long-distance relationship but make it cryptography 🔐

depending on its config (peep the options section, bestie), this module requires that a secret file is manually set up for each account on the system. that secret file holds the secret key AND the user-specific options (see google-authenticator(1)). unless you use the nullok option, authentication tries get rejected if that secret file doesn't exist. alternatively, a system administrator can create those secret files on behalf of the users and then just… tell them the secret keys. main character sysadmin energy 👑

💅 OPTIONS 💅

• secret=file — point the module at a non-standard file location for the secret file.
  • by default, the PAM module looks for the secret file in the .google_authenticator file inside the home of the user logging in. this option overrides that location. periodt.
  • the location you hand over may include these short-hands:
    • ${USER} — gets interpreted as the username.
    • ${HOME} and ~ — get interpreted as the user's home directory.
• authtok_prompt=prompt — override the default token prompt.
  • heads up bestie: if there are spaces in the prompt you provide, the whole argument must be wrapped in square brackets.
• user=username — switch to a hard-coded user prior to doing any file operation. set it and forget it.
• no_strict_owner — disable the check against the secret file's owner.
  • by default, the secret file must be owned by the user logging in. this option turns that check off.
• allowed_perm=0nnn — override the checked permissions of the secret file.
  • by default, the secret file must be readable only by its owner (ie. mode 0600). this option lets you specify a different mode for this file.
• debug — enable more verbose log messages in syslog. for when you need to see everything 👀
• try_first_pass|use_first_pass|forward_pass — stacking options for this PAM module.
  • because some PAM clients literally cannot prompt the user for more than just the password, these stacking options exist:
    • try_first_pass: before prompting the user for the one-time code, this module first tries the previous stacked module's password, in case that satisfies this module as well.
    • use_first_pass: force this module to use a previous stacked module's password. with this option, this module will never prompt the user for the one-time code. so if no valid one-time code is available, the user gets denied access. bye 👋
    • forward_pass: query the user for both the system password and the verification code in a single prompt. the system password is then forwarded to the next PAM module, which will have to be configured with either the use_first_pass option, or the try_first_pass option.
• noskewadj — don't adjust time skew automatically.
  • by default, the PAM module makes an attempt to compensate for time skew between the server and the device on which one-time passcodes are generated. this option disables that behavior.
  • note that this option is only relevant for time-based (TOTP) mode.
• no_increment_hotp — don't increment the counter for failed attempts.
  • in some circonstance, failed passwords still get an OTP prompt. this option disables counter incrementation in such situations.
  • note that this option is only relevant for counter-based (HOTP) mode.
• nullok — allow users to log in without OTP, if they haven't set up OTP yet.
  • during the initial roll-out process, not all users may have created a secret key yet. this option lets them log in anyway, even if the secret file doesn't exist. very forgiving of you 💜
• echo_verification_code — echo the verification code when it is entered by the user.

👑 MODULE TYPE PROVIDED 👑

only the auth module type is provided. that's it. that's the whole list. one and done. slay.

🌈 RETURN VALUES 🌈

• PAM_SUCCESS — either the provided one-time code is correct, or it's a valid emergency code. we love a win ✨
• PAM_IGNORE — this module is ignored.
• PAM_AUTH_ERR — the provided one-time code isn't correct and isn't a valid emergency code, or an error was encountered. it's giving rejected 💀

🎀 EXAMPLES 🎀

these lines may be used to enable this PAM module, bestie:

• auth required pam_google_authenticator.so no_increment_hotp # Make sure the counter (for HOTP mode) isn't incremented for failed attempts.
• auth required pam_google_authenticator.so nullok # Allow users to log in if their secret files don't exist
• auth required pam_google_authenticator.so secret=/var/unencrypted-home/${USER}/.google_authenticator # Store secret files in a specific location
• auth required pam_google_authenticator.so [authtok_prompt=Your secret token: ] # Use a specific prompt
• auth required pam_google_authenticator.so noskewadj # Don't compensate time skew automatically

🔥 SECURITY NOTES 🔥

for highest security, make sure that both password and one-time code are being requested even if the password and/or the one-time code are incorrect. that means at least the first of pam_unix.so (or whatever other module is used to verify passwords) and pam_google_authenticator.so should be set as required, not requisite. this one matters, don't skip it, iykyk 🫶

⭐ SEE ALSO ⭐

• google-authenticator(1).
• the Google Authenticator source code and all documentation may be downloaded from <https://github.com/google/google-authenticator-libpam>. go get it, bestie 🧚

and that's the whole page!! this was the Google Authenticator PAM module manual, page PAM_GOOGLE_AUTHENTICATOR(8) — ty for reading, you ate 💖✨🎀