1PAM_GOOGLE_AUTHENTICATOR(8) PAM_GOOGLE_AUTHENTICATOR(8)
2
6 pam_google_authenticator - PAM module for Google two-factor authentica‐
7 tion
8
10 pam_google_authenticator.so [secret=file] [authtok_prompt=prompt] [us‐
11 er=username] [no_strict_owner] [allowed_perm=0nnn] [debug]
12 [try_first_pass|use_first_pass|forward_pass] [noskewadj] [no_incre‐
13 ment_hotp] [nullok] [echo_verification_code]
14
16 The pam_google_authenticator module is designed to protect user authen‐
17 tication with a second factor, either time-based (TOTP) or
18 counter-based (HOTP). Prior logging in, the user will be asked for
19 both its password and a one-time code. Such one-time codes can be gen‐
20 erated with the Google Authenticator application, installed on the us‐
21 er's Android device. To respectively generate and verify those
22 one-time codes, a secret key (randomly generated) must be shared be‐
23 tween the device on which one-time codes are generated and the system
24 on which this PAM module is enabled.
25 Depending on its configuration (see options section), this module re‐
27 quires that a secret file is manually set up for each account on the
28 system. This secret file holds the secret key and user-specific op‐
29 tions (see google-authenticator(1)). Unless the nullok option is used,
30 authentication tries will be rejected if such secret file doesn't ex‐
31 ist. Alternatively, a system administrator may create those secret
32 files on behalf of the users and then communicates to them the secret
33 keys.
34
36 secret=file
37 Specify a non-standard file location for the secret file.
38 By default, the PAM module looks for the secret file in the
40 .google_authenticator file within the home of the user logging
41 in. This option overrides this location.
42 The provided location may include the following short-hands:
44 · ${USER} that will be interpreted as the username.
46 · ${HOME} and ~ that will be interpreted as the user's home di‐
48 rectory.
49 authtok_prompt=prompt
51 Override default token prompt.
52 Note that if spaces are present in the provided prompt, the
54 whole argument must be wrapped in square brackets.
55 user=username
57 Switch to a hard-coded user prior to doing any file operation.
58 no_strict_owner
60 Disable the check against the secret file's owner.
61 By default, the secret file must be owned by the user logging
63 in. This option disables this check.
64 allowed_perm=0nnn
66 Override checked permissions of the secret file.
67 By default, the secret file must be readable only by its owner
69 (ie. mode 0600). This option allows a different mode to be
70 specified for this file.
71 debug Enable more verbose log messages in syslog.
73 try_first_pass|use_first_pass|forward_pass
75 Stacking options for this PAM module.
76 Because some PAM clients cannot prompt the user for more than
78 just the password, the following stacking options may be used:
79 · try_first_pass: before prompting the user for the one-time
81 code, this module first tries the previous stacked module's
82 password in case that satisfies this module as well.
83 · use_first_pass: force this module to use a previous stacked
85 modules password. With this option, this module will never
86 prompt the user for the one-time code. Thus, if no valid
87 one-time code is available, the user will be denied access.
88 · forward_pass: query the user for both the system password and
90 the verification code in a single prompt. The system password
91 is then forwarded to the next PAM module, which will have to
92 be configured with either the use_first_pass option, or the
93 try_first_pass option.
94 noskewadj
96 Don't adjust time skew automatically.
97 By default, the PAM module makes an attempt to compensate for
99 time skew between the server and the device on which one-time
100 passcodes are generated. This option disable this behavior.
101 Note that this option is only relevant for time-based (TOTP)
103 mode.
104 no_increment_hotp
106 Don't increment the counter for failed attempts.
107 In some circonstance, failed passwords still get an OTP prompt.
109 This option disables counter incrementation is such situations.
110 Note that this option is only relevant for counter-based (HOTP)
112 mode.
113 nullok Allow users to log in without OTP, if they haven't set up OTP
115 yet.
116 During the initial roll-out process, all users may not have cre‐
118 ated a secret key yet. This option allows them to log in, even
119 if the secret file doesn't exist.
120 echo_verification_code
122 Echo the verification code when it is entered by the user.
123
125 Only the auth module type is provided.
126
128 PAM_SUCCESS
129 Either the provided one-time code is correct or is a valid emer‐
130 gency code.
131 PAM_IGNORE
133 This module is ignored.
134 PAM_AUTH_ERR
136 The provided one-time code isn't correct and isn't a valid emer‐
137 gency code, or an error was encountered.
138
140 The following lines may be used to enable this PAM module:
141 · auth required pam_google_authenticator.so no_increment_hotp # Make
143 sure the counter (for HOTP mode) isn't incremented for failed at‐
144 tempts.
145 · auth required pam_google_authenticator.so nullok # Allow users to log
147 in if their secret files don't exist
148 · auth required pam_google_authenticator.so secret=/var/unencrypt‐
150 ed-home/${USER}/.google_authenticator # Store secret files in a spe‐
151 cific location
152 · auth required pam_google_authenticator.so [authtok_prompt=Your se‐
154 cret token: ] # Use a specific prompt
155 · auth required pam_google_authenticator.so noskewadj # Don't compen‐
157 sate time skew automatically
158
160 For highest security, make sure that both password and one-time code
161 are being requested even if password and/or one-time code are incor‐
162 rect. This means that at least the first of pam_unix.so (or whatever
163 other module is used to verify passwords) and pam_google_authentica‐
164 tor.so should be set as required, not requisite.
165
167 google-authenticator(1).
168 The Google Authenticator source code and all documentation may be down‐
170 loaded from <https://github.com/google/google-authenticator-libpam>.
171Google Authenticator PAM module manual PAM_GOOGLE_AUTHENTICATOR(8)