{ "mode": "man", "parameter": "PAM_GOOGLE_AUTHENTICATOR", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/PAM_GOOGLE_AUTHENTICATOR/8/json", "generated": "2026-06-14T00:53:49Z", "synopsis": "pamgoogleauthenticator.so [secret=file] [authtokprompt=prompt] [user=username]\n[nostrictowner] [allowedperm=0nnn] [debug] [tryfirstpass|usefirstpass|forwardpass]\n[noskewadj] [noincrementhotp] [nullok] [echoverificationcode]", "sections": { "NAME": { "content": "pamgoogleauthenticator - PAM module for Google two-factor authentication\n", "subsections": [] }, "SYNOPSIS": { "content": "pamgoogleauthenticator.so [secret=file] [authtokprompt=prompt] [user=username]\n[nostrictowner] [allowedperm=0nnn] [debug] [tryfirstpass|usefirstpass|forwardpass]\n[noskewadj] [noincrementhotp] [nullok] [echoverificationcode]\n", "subsections": [] }, "DESCRIPTION": { "content": "The pamgoogleauthenticator module is designed to protect user authentication with a second\nfactor, either time-based (TOTP) or counter-based (HOTP). Prior logging in, the user will be\nasked for both its password and a one-time code. Such one-time codes can be generated with\nthe Google Authenticator application, installed on the user's Android device. To respective‐\nly generate and verify those one-time codes, a secret key (randomly generated) must be shared\nbetween the device on which one-time codes are generated and the system on which this PAM\nmodule is enabled.\n\nDepending on its configuration (see options section), this module requires that a secret file\nis manually set up for each account on the system. This secret file holds the secret key and\nuser-specific options (see google-authenticator(1)). Unless the nullok option is used, au‐\nthentication tries will be rejected if such secret file doesn't exist. Alternatively, a sys‐\ntem administrator may create those secret files on behalf of the users and then communicates\nto them the secret keys.\n", "subsections": [] }, "OPTIONS": { "content": "secret=file\nSpecify a non-standard file location for the secret file.\n\nBy default, the PAM module looks for the secret file in the .googleauthenticator file\nwithin the home of the user logging in. This option overrides this location.\n\nThe provided location may include the following short-hands:\n\n• ${USER} that will be interpreted as the username.\n\n• ${HOME} and ~ that will be interpreted as the user's home directory.\n\nauthtokprompt=prompt\nOverride default token prompt.\n\nNote that if spaces are present in the provided prompt, the whole argument must be\nwrapped in square brackets.\n\nuser=username\nSwitch to a hard-coded user prior to doing any file operation.\n\nnostrictowner\nDisable the check against the secret file's owner.\n\nBy default, the secret file must be owned by the user logging in. This option dis‐\nables this check.\n\nallowedperm=0nnn\nOverride checked permissions of the secret file.\n\nBy default, the secret file must be readable only by its owner (ie. mode 0600). This\noption allows a different mode to be specified for this file.\n\ndebug Enable more verbose log messages in syslog.\n\ntryfirstpass|usefirstpass|forwardpass\nStacking options for this PAM module.\n\nBecause some PAM clients cannot prompt the user for more than just the password, the\nfollowing stacking options may be used:\n\n• tryfirstpass: before prompting the user for the one-time code, this module first\ntries the previous stacked module's password in case that satisfies this module as\nwell.\n\n• usefirstpass: force this module to use a previous stacked modules password. With\nthis option, this module will never prompt the user for the one-time code. Thus, if\nno valid one-time code is available, the user will be denied access.\n\n• forwardpass: query the user for both the system password and the verification code\nin a single prompt. The system password is then forwarded to the next PAM module,\nwhich will have to be configured with either the usefirstpass option, or the\ntryfirstpass option.\n", "subsections": [ { "name": "noskewadj", "content": "Don't adjust time skew automatically.\n\nBy default, the PAM module makes an attempt to compensate for time skew between the\nserver and the device on which one-time passcodes are generated. This option disable\nthis behavior.\n\nNote that this option is only relevant for time-based (TOTP) mode.\n\nnoincrementhotp\nDon't increment the counter for failed attempts.\n\nIn some circonstance, failed passwords still get an OTP prompt. This option disables\ncounter incrementation is such situations.\n\nNote that this option is only relevant for counter-based (HOTP) mode.\n\nnullok Allow users to log in without OTP, if they haven't set up OTP yet.\n\nDuring the initial roll-out process, all users may not have created a secret key yet.\nThis option allows them to log in, even if the secret file doesn't exist.\n\nechoverificationcode\nEcho the verification code when it is entered by the user.\n" } ] }, "MODULE TYPE PROVIDED": { "content": "Only the auth module type is provided.\n", "subsections": [] }, "RETURN VALUES": { "content": "PAMSUCCESS\nEither the provided one-time code is correct or is a valid emergency code.\n\nPAMIGNORE\nThis module is ignored.\n\nPAMAUTHERR\nThe provided one-time code isn't correct and isn't a valid emergency code, or an error\nwas encountered.\n", "subsections": [] }, "EXAMPLES": { "content": "The following lines may be used to enable this PAM module:\n\n• auth required pamgoogleauthenticator.so noincrementhotp # Make sure the counter (for\nHOTP mode) isn't incremented for failed attempts.\n\n• auth required pamgoogleauthenticator.so nullok # Allow users to log in if their secret\nfiles don't exist\n\n• auth required pamgoogleauthenticator.so secret=/var/unencrypted-home/${USER}/.googleau‐\nthenticator # Store secret files in a specific location\n\n• auth required pamgoogleauthenticator.so [authtokprompt=Your secret token: ] # Use a spe‐\ncific prompt\n\n• auth required pamgoogleauthenticator.so noskewadj # Don't compensate time skew automati‐\ncally\n", "subsections": [] }, "SECURITY NOTES": { "content": "For highest security, make sure that both password and one-time code are being requested even\nif password and/or one-time code are incorrect. This means that at least the first of\npamunix.so (or whatever other module is used to verify passwords) and pamgoogleauthentica‐\ntor.so should be set as required, not requisite.\n", "subsections": [] }, "SEE ALSO": { "content": "google-authenticator(1).\n\nThe Google Authenticator source code and all documentation may be downloaded from\n.\n\n\n\nGoogle Authenticator PAM module manual PAMGOOGLEAUTHENTICATOR(8)", "subsections": [] } }, "summary": "pamgoogleauthenticator - PAM module for Google two-factor authentication", "flags": [], "examples": [ "The following lines may be used to enable this PAM module:", "• auth required pamgoogleauthenticator.so noincrementhotp # Make sure the counter (for", "HOTP mode) isn't incremented for failed attempts.", "• auth required pamgoogleauthenticator.so nullok # Allow users to log in if their secret", "files don't exist", "• auth required pamgoogleauthenticator.so secret=/var/unencrypted-home/${USER}/.googleau‐", "thenticator # Store secret files in a specific location", "• auth required pamgoogleauthenticator.so [authtokprompt=Your secret token: ] # Use a spe‐", "cific prompt", "• auth required pamgoogleauthenticator.so noskewadj # Don't compensate time skew automati‐", "cally" ], "see_also": [ { "name": "google-authenticator", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/google-authenticator/1/json" } ] }