1PAM_GOOGLE_AUTHENTICATOR(8)                        PAM_GOOGLE_AUTHENTICATOR(8)
2
3
4

NAME

6       pam_google_authenticator - PAM module for Google two-factor authentica‐
7       tion
8

SYNOPSIS

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

DESCRIPTION

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
26       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

OPTIONS

36       secret=file
37              Specify a non-standard file location for the secret file.
38
39              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
43              The provided location may include the following short-hands:
44
45              · ${USER} that will be interpreted as the username.
46
47              · ${HOME} and ~ that will be interpreted as the user's home  di‐
48                rectory.
49
50       authtok_prompt=prompt
51              Override default token prompt.
52
53              Note  that  if  spaces  are  present in the provided prompt, the
54              whole argument must be wrapped in square brackets.
55
56       user=username
57              Switch to a hard-coded user prior to doing any file operation.
58
59       no_strict_owner
60              Disable the check against the secret file's owner.
61
62              By default, the secret file must be owned by  the  user  logging
63              in.  This option disables this check.
64
65       allowed_perm=0nnn
66              Override checked permissions of the secret file.
67
68              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
72       debug  Enable more verbose log messages in syslog.
73
74       try_first_pass|use_first_pass|forward_pass
75              Stacking options for this PAM module.
76
77              Because  some  PAM  clients cannot prompt the user for more than
78              just the password, the following stacking options may be used:
79
80              · 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
84              · 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
89              · 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
95       noskewadj
96              Don't adjust time skew automatically.
97
98              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
102              Note  that  this  option  is only relevant for time-based (TOTP)
103              mode.
104
105       no_increment_hotp
106              Don't increment the counter for failed attempts.
107
108              In some circonstance, failed passwords still get an OTP  prompt.
109              This option disables counter incrementation is such situations.
110
111              Note  that this option is only relevant for counter-based (HOTP)
112              mode.
113
114       nullok Allow users to log in without OTP, if they haven't  set  up  OTP
115              yet.
116
117              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
121       echo_verification_code
122              Echo the verification code when it is entered by the user.
123

MODULE TYPE PROVIDED

125       Only the auth module type is provided.
126

RETURN VALUES

128       PAM_SUCCESS
129              Either the provided one-time code is correct or is a valid emer‐
130              gency code.
131
132       PAM_IGNORE
133              This module is ignored.
134
135       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

EXAMPLES

140       The following lines may be used to enable this PAM module:
141
142       · 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
146       · auth required pam_google_authenticator.so nullok # Allow users to log
147         in if their secret files don't exist
148
149       · 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
153       · auth required pam_google_authenticator.so [authtok_prompt=Your se‐
154         cret token: ] # Use a specific prompt
155
156       · auth required pam_google_authenticator.so noskewadj  #  Don't compen‐
157         sate time skew automatically
158

SECURITY NOTES

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

SEE ALSO

167       google-authenticator(1).
168
169       The Google Authenticator source code and all documentation may be down‐
170       loaded from <https://github.com/google/google-authenticator-libpam>.
171
172
173
174Google Authenticator PAM module manual             PAM_GOOGLE_AUTHENTICATOR(8)
Impressum