1# Google Authenticator PAM module 2 3Example PAM module demonstrating two-factor authentication for logging 4into servers via SSH, OpenVPN, etc… 5 6This project is not about logging in to Google, Facebook, or other 7TOTP/HOTP second factor systems, even if they recommend using the 8Google Authenticator apps. 9 10[](https://travis-ci.org/google/google-authenticator-libpam) 11 12## Build & install 13```shell 14./bootstrap.sh 15./configure 16make 17sudo make install 18``` 19 20If you don't have access to "sudo", you have to manually become "root" prior 21to calling "make install". 22 23## Setting up the PAM module for your system 24 25For highest security, make sure that both password and OTP are being requested 26even if password and/or OTP are incorrect. This means that *at least* the first 27of `pam_unix.so` (or whatever other module is used to verify passwords) and 28`pam_google_authenticator.so` should be set as `required`, not `requisite`. It 29probably can't hurt to have both be `required`, but it could depend on the rest 30of your PAM config. 31 32If you use HOTP (counter based as opposed to time based) then add the option 33`no_increment_hotp` to make sure the counter isn't incremented for failed 34attempts. 35 36Add this line to your PAM configuration file: 37 38` auth required pam_google_authenticator.so no_increment_hotp` 39 40## Setting up a user 41 42Run the `google-authenticator` binary to create a new secret key in your home 43directory. These settings will be stored in `~/.google_authenticator`. 44 45If your system supports the "libqrencode" library, you will be shown a QRCode 46that you can scan using the Android "Google Authenticator" application. 47 48If your system does not have this library, you can either follow the URL that 49`google-authenticator` outputs, or you have to manually enter the alphanumeric 50secret key into the Android "Google Authenticator" application. 51 52In either case, after you have added the key, click-and-hold until the context 53menu shows. Then check that the key's verification value matches (this feature 54might not be available in all builds of the Android application). 55 56Each time you log into your system, you will now be prompted for your TOTP code 57(time based one-time-password) or HOTP (counter-based), depending on options 58given to `google-authenticator`, after having entered your normal user id and 59your normal UNIX account password. 60 61During the initial roll-out process, you might find that not all users have 62created a secret key yet. If you would still like them to be able to log 63in, you can pass the "nullok" option on the module's command line: 64 65` auth required pam_google_authenticator.so nullok` 66 67## Encrypted home directories 68 69If your system encrypts home directories until after your users entered their 70password, you either have to re-arrange the entries in the PAM configuration 71file to decrypt the home directory prior to asking for the OTP code, or 72you have to store the secret file in a non-standard location: 73 74` auth required pam_google_authenticator.so secret=/var/unencrypted-home/${USER}/.google_authenticator` 75 76would be a possible choice. Make sure to set appropriate permissions. You also 77have to tell your users to manually move their .google_authenticator file to 78this location. 79 80In addition to "${USER}", the `secret=` option also recognizes both "~" and 81`${HOME}` as short-hands for the user's home directory. 82 83When using the `secret=` option, you might want to also set the `user=` 84option. The latter forces the PAM module to switch to a dedicated hard-coded 85user id prior to doing any file operations. When using the `user=` option, you 86must not include "~" or "${HOME}" in the filename. 87 88The `user=` option can also be useful if you want to authenticate users who do 89not have traditional UNIX accounts on your system. 90 91## Module options 92 93### secret=/path/to/secret/file 94 95See "encrypted home directories", above. 96 97### authtok_prompt=prompt 98 99Overrides default token prompt. If you want to include spaces in the prompt, 100wrap the whole argument in square brackets: 101 102` auth required pam_google_authenticator.so [authtok_prompt=Your secret token: ]` 103 104### user=some-user 105 106Force the PAM module to switch to a hard-coded user id prior to doing any file 107operations. Commonly used with `secret=`. 108 109### no_strict_owner 110 111DANGEROUS OPTION! 112 113By default the PAM module requires that the secrets file must be owned the user 114logging in (or if `user=` is specified, owned by that user). This option 115disables that check. 116 117This option can be used to allow daemons not running as root to still handle 118configuration files not owned by that user, for example owned by the users 119themselves. 120 121### allowed_perm=0nnn 122 123DANGEROUS OPTION! 124 125By default, the PAM module requires the secrets file to be readable only by the 126owner of the file (mode 0600 by default). In situations where the module is used 127in a non-default configuration, an administrator may need more lenient file 128permissions, or a specific setting for their use case. 129 130### debug 131 132Enable more verbose log messages in syslog. 133 134### try_first_pass / use_first_pass / forward_pass 135 136Some PAM clients cannot prompt the user for more than just the password. To 137work around this problem, this PAM module supports stacking. If you pass the 138`forward_pass` option, the `pam_google_authenticator` module queries the user 139for both the system password and the verification code in a single prompt. 140It then forwards the system password to the next PAM module, which will have 141to be configured with the `use_first_pass` option. 142 143In turn, `pam_google_authenticator` module also supports both the standard 144`use_first_pass` and `try_first_pass` options. But most users would not need 145to set those on the `pam_google_authenticator`. 146 147### noskewadj 148 149If you discover that your TOTP code never works, this is most commonly the 150result of the clock on your server being different from the one on your Android 151device. The PAM module makes an attempt to compensate for time skew. You can 152teach it about the amount of skew that you are experiencing, by trying to log 153it three times in a row. Make sure you always wait 30s (but not longer), so 154that you get three distinct TOTP codes. 155 156Some administrators prefer that time skew isn't adjusted automatically, as 157doing so results in a slightly less secure system configuration. If you want 158to disable it, you can do so on the module command line: 159 160` auth required pam_google_authenticator.so noskewadj` 161 162### no_increment_hotp 163 164Don't increment the counter for failed HOTP attempts. Normally you should set 165this so failed password attempts by an attacker without a token don't lock out 166the authorized user. 167 168### nullok 169 170Allow users to log in without OTP, if they haven't set up OTP yet. 171 172PAM requires at least one `SUCCESS` answer from a module, and `nullok` 173causes this module to say `IGNORE`. This means that if this option is 174used at least one other module must have said `SUCCESS`. One way to do 175this is to add `auth required pam_permit.so` to the end of the PAM 176config. 177 178### echo_verification_code 179 180By default, the PAM module does not echo the verification code when it is 181entered by the user. In some situations, the administrator might prefer a 182different behavior. Pass the `echo_verification_code` option to the module 183in order to enable echoing. 184 185If you would like verification codes that are counter based instead of 186timebased, use the `google-authenticator` binary to generate a secret key in 187your home directory with the proper option. In this mode, clock skew is 188irrelevant and the window size option now applies to how many codes beyond the 189current one that would be accepted, to reduce synchronization problems. 190 191### grace_period=seconds 192 193If present and non-zero, provide a grace period during which a second 194verification code will not be requested. Try setting seconds to 86400 195to allow a full-day between requesting codes; or 3600 for an hour. 196 197This works by adding an (IP address, timestamp) pair to the security 198file after a successful one-time-password login; 199only the last ten distinct IP addresses are tracked. 200 201### allow_readonly 202 203DANGEROUS OPTION! 204 205With this option an attacker with ability to fill up the filesystem (flood 206server with web requests, or if they have an account just fill the disk up) can 207force a situation where one-time-passwords can be reused, defeating the purpose 208of "one time". 209 210By default, if the `grace_period` option is defined the PAM module requires 211some free space to store the IP address and timestamp of the last login. 212It could prevent access if a server has no free space or in case of an 213update config file error. With the `allow_readonly` option you can ignore 214any errors which could occur during config file update. 215
){kind=link}