1PAM_AFS_SESSION(5) pam-afs-session PAM_AFS_SESSION(5)
2
6 pam_afs_session - AFS PAG and token PAM module
7
9 auth optional pam_afs_session.so
10 session required pam_afs_session.so
11
13 The AFS session service module for PAM, typically installed at
14 /lib/security/pam_afs_session.so, establishes new AFS sessions and
15 obtains AFS tokens when a new session is opened for a user. It is a
16 shared object that is dynamically loaded by the PAM subsystem as
17 necessary, based on the system PAM configuration. PAM is a system for
18 plugging in external authentication and session management modules so
19 that each application doesn't have to know the best way to check user
20 authentication or create a user session on that system. For details on
21 how to configure PAM on your system, see the PAM man page, often
22 pam(7).
23 This module provides pam_setcred, pam_open_session, and
25 pam_close_session implementations for AFS. Because pam_setcred is part
26 of the auth PAM group, it also implements a dummy pam_authenticate that
27 always succeeds (otherwise, it can't provide a pam_setcred).
28 Make sure that this module is NEVER listed as "sufficient" or as the
30 only "required" module in the auth group. Doing so will potentially
31 allow users to log on without any password. There unfortunately isn't
32 a way to work around this and still provide pam_setcred without running
33 afoul of a bug in (at least) Linux PAM 0.99.7.1 and probably earlier
34 that causes authentication to fail when the final module in the auth
35 group returns PAM_IGNORE and "[default=done]" was given as the action.
36 Here are the actions of this module:
38 pam_open_session
40 When a new session is opened, this module will first check to see
41 if AFS is running on the system. If not, it will log a message and
42 exit successfully. If AFS is running, it will place the user's
43 session in a new PAG (Process Authentication Group, often
44 implemented as supplemental groups, which limits user tokens to
45 only processes in that PAG). It will then attempt to obtain
46 tokens, either directly if built with the Heimdal libkafs library
47 and Kerberos support or by running an external aklog program. If
48 PAG creation fails, the module will fail; if obtaining tokens
49 fails, the module will log a warning but still return success.
50 The module will only attempt to obtain tokens if the environment
52 variable KRB5CCNAME is set in the environment, unless otherwise
53 configured (see the always_aklog option). It will always create a
54 new PAG, however.
55 pam_close_session
57 If and only if pam_open_session successfully obtained AFS tokens
58 and AFS is still running on the system, pam_close_session will
59 delete the tokens in the current PAG (equivalent to running unlog).
60 To leave the tokens after session close, set the retain_after_close
61 option.
62 pam_setcred
64 When pam_setcred is called with the PAM_ESTABLISH_CRED flag, it
65 will do the same as if pam_open_session was called. When
66 pam_setcred is called with the PAM_DELETE_CRED flag, it will do the
67 same as if pam_close_session was called. When called with the
68 PAM_REINITIALIZE_CRED flag or the PAM_REFRESH_CRED flag, it won't
69 create a new PAG but instead will only attempt to get new tokens
70 (still skipping this unless KRB5CCNAME is set in the environment or
71 always_aklog is set).
72 This module is primarily intended for use with a Kerberos
74 authentication module. It does not itself do any user authentication;
75 it cannot, for instance, be used to authenticate users to a kaserver.
76 While it is intended for use with an aklog that uses Kerberos ticket
77 caches to obtain tokens, it can be used with any aklog implementation
78 (always_aklog may have to be set if no Kerberos ticket cache will be
79 present).
80 This module performs no authorization checks and does not hook into
82 password changes; it only implements the session functions and
83 pam_setcred.
84
86 The AFS session PAM module supports the following configuration
87 options, which may be set in the PAM configuration as arguments listed
88 after "pam_afs_session.so" or in the system krb5.conf.
89 Some of them take arguments, in which case the argument will be given
91 after "=". The rest are boolean options. To set a boolean option in
92 the PAM configuration, just give the name of the option in the
93 arguments. To set an option that takes an argument, follow the option
94 name with an equal sign ("=") and the value, with no separating
95 whitespace. Whitespace in option arguments is not supported in the PAM
96 configuration files of most PAM implementations.
97 To set an option for the PAM module in the system krb5.conf file, put
99 that option in the [appdefaults] section. The AFS session PAM module
100 will look for options either at the top level of the [appdefaults]
101 section or in a subsection named "pam-afs-session" (currently, realm-
102 specific configuration is not checked). For example, the following
103 fragment of a krb5.conf file would set aklog_homedir to true and
104 minimum_uid to 100.
105 [appdefaults]
107 aklog_homedir = true
108 pam-afs-session = {
109 minimum_uid = 100
110 }
111 There is no difference to the PAM module whether options are specified
113 at the top level or in a "pam-afs-session" section; the
114 "pam-afs-session" section is supported in case there are options that
115 should be set for the PAM module but not for other applications. For
116 more information on the syntax of krb5.conf, see krb5.conf(5).
117 If the same option is set in krb5.conf and in the PAM configuration,
119 the latter takes precedent. Note, however, that due to the
120 configuration syntax, there's no way to turn off a boolean option in
121 the PAM configuration that was turned on in krb5.conf.
122 afs_cells=cell[,cell...]
124 Obtain tokens for the listed cells instead of the default local
125 cell. If more than one cell is listed, try to obtain tokens for
126 each cell. If specified in krb5.conf, the cells can be separated
127 by any combination of spaces and commas; if specified in the PAM
128 configuration, they must be separated by commas.
129 If the AFS session PAM module is running an external program, this
131 option is implemented by passing a -c flag with the cell as its
132 argument for each listed cell to that program. If aklog_homedir is
133 also set, the -c flags and the -p flag will all be passed to the
134 external program.
135 aklog_homedir
137 Try to obtain the necessary tokens to access the user's home
138 directory. If the libkafs token-obtaining API is used, setting
139 this will cause the AFS session PAM module to pass the user's home
140 directory into that API and request that the appropriate tokens be
141 obtained. If running an external aklog program, aklog will be
142 called with -p home-directory where home-directory is the home
143 directory of the local user for which the session is being opened
144 or refreshed. This generally will tell aklog to check that path,
145 find all AFS cells involved in access to that path, and attempt to
146 obtain tokens for each one. Note that this means that if the
147 user's home directory is not in AFS, no tokens will be obtained.
148 In either case, the user's home directory is obtained via
150 getpwnam() based on the username PAM says we are authenticating.
151 always_aklog
153 Normally, the AFS session PAM module only tries to obtain tokens if
154 KRB5CCNAME is set in the PAM environment. If this option is set,
155 it will always attempt to obtain tokens. This is only useful if it
156 is configured to run an external aklog program.
157 This can be used if your environment doesn't correctly set
159 KRB5CCNAME in the environment for some reason, or if your aklog
160 doesn't rely on a Kerberos ticket cache to obtain tokens (or can
161 find the cache on its own via some other means).
162 debug
164 If this option is set, additional trace information will be logged
165 to syslog with priority LOG_DEBUG.
166 ignore_root
168 If this option is set, the AFS session PAM module won't take any
169 action (and will exit successfully) if the account for which the
170 session is being established is named "root".
171 kdestroy
173 If this option is set and the AFS session PAM module was built with
174 Kerberos support, the user's ticket cache will be destroyed after
175 tokens are obtained successfully. If tokens are not obtained
176 successfully, the ticket cache will be left intact. Please note
177 that this is not properly a security feature, since the ticket
178 cache will still be written to disk between the time the Kerberos
179 PAM module authenticates the user and the time the AFS session PAM
180 module is run. It can, however, be used to reduce the window
181 during which Kerberos ticket caches are lying about if the only use
182 one has for ticket caches is to obtain AFS tokens.
183 minimum_uid=uid
185 If this option is set, the AFS session PAM module won't take any
186 action (and will exit successfully) if the account for which the
187 session is being established has a UID lower than uid.
188 nopag
190 If this option is set, no PAG will be created. Be careful when
191 using this option, since it means that the user will inherit a PAG
192 from the process managing the login. If sshd, for instance, is
193 started in a PAG, every user who logs in via ssh will be put in the
194 same PAG and will share tokens if this option is used.
195 This is the default on Mac OS X, where PAGs are not supported.
197 notokens
199 If this option is set, the AFS session PAM module will only create
200 a PAG and not attempt to obtain tokens. Setting this option
201 overrides all other settings related to acquiring tokens, including
202 always_aklog. If both nopag and notokens are set, the module
203 essentially does nothing.
204 Setting notokens also implies retain_after_close, meaning that the
206 AFS session PAM module will also not attempt to delete tokens when
207 the user's session ends.
208 program=path
210 The path to the aklog program to run. Setting this option tells
211 the AFS session PAM module to always run an external program to
212 obtain tokens and never use the libkafs interface, even if the
213 latter is available.
214 You may pass options to this program by separating them with commas
216 (or spaces or tabs in krb5.conf or if the configuration syntax of
217 your PAM configuration allows this). For example, the setting:
218 program=/usr/bin/aklog,-noprdb,-524
220 will run "/usr/bin/aklog -noprdb -524" as the program to obtain
222 tokens. The arguments are passed directly, not parsed by the
223 shell.
224 If this option is not set, the default behavior is to call the
226 libkafs function to obtain tokens, if available, and otherwise to
227 use a default path to aklog determined at compile time (the first
228 aklog found on the compiler's path by default). If no aklog could
229 be found at compile time and libkafs isn't used, this option must
230 be set.
231 retain_after_close
233 If this option is set, pam_close_session will do nothing
234 (successfully) rather than deleting tokens. This will allow
235 programs started in the user's PAG that are still running when the
236 log out to continue to use the user's tokens until they expire.
237 Normally, the AFS kernel module will automatically clean up tokens
238 once every process in that PAG has terminated.
239
241 KRB5CCNAME
242 This module looks for KRB5CCNAME in the PAM environment and by
243 default does not run aklog if it is not set.
244 The entire PAM environment is passed to aklog as its environment
246 (rather than the environment of the process running the PAM functions).
247
249 As mentioned above, this module implements a dummy pam_authenticate
250 function so that it can provide a pam_setcred function. Never list
251 this module as "sufficient" or as the only "required" module or you may
252 allow users to log on without a password.
253 While spawning an external aklog program, the AFS session PAM module
255 resets the SIGCHLD signal handler to the default handler while the
256 program runs and then restores it afterward. This is done to avoid
257 having aklog interfere with process handling in the calling
258 application, but it means that there's a race condition that can cause
259 children to be incorrectly handled if they exit while aklog is running.
260 There is unfortunately no good solution to this other than building
261 against Heimdal and using the libkafs interface to obtain tokens
262 instead of an external program.
263 To detect whether AFS is running on the system, the AFS session PAM
265 module temporarily sets a SIGSYS handler before attempting an AFS
266 system call. That handler may also modify a static variable. Neither
267 of these should ideally be done in a PAM module, but there is no other
268 good way of checking for the non-existence of a system call that
269 doesn't crash the application on some operating systems. The PAM
270 module will attempt to restore the previous SIGSYS handler, if any,
271 after the test is done, and the static variable is used in such a way
272 that running it from multiple threads shouldn't be an issue, but be
273 aware that the PAM module is doing this behind the back of the
274 application and may interfere with unusual SIGSYS handlers or similar
275 application actions.
276
278 When using the libkafs interface to obtain tokens, be sure that it is
279 configured properly for the type of AFS tokens expected at your site.
280 As of Heimdal 0.7, the default behavior is to contact the krb524
281 service to translate Kerberos v5 tickets into Kerberos v4 tickets to
282 use as tokens. AFS cells running current server software no longer
283 need this, and if your site doesn't run the krb524 service, this may
284 break token acquisition.
285 Sites running AFS servers that understand Kerberos-v5-derived tokens
287 should add configuration like:
288 libkafs = {
290 EXAMPLE.ORG = {
291 afs-use-524 = no
292 }
293 }
294 to the [appdefaults] section of their krb5.conf files to disable use of
296 the krb524 service. See the Heimdal kafs(3) man page for more
297 information.
298
300 Copyright 2015 Russ Allbery <eagle@eyrie.org>
301 Copyright 2005, 2006, 2007, 2008, 2009, 2010, 2011 The Board of
303 Trustees of the Leland Stanford Junior University
304 Copying and distribution of this file, with or without modification,
306 are permitted in any medium without royalty provided the copyright
307 notice and this notice are preserved. This file is offered as-is,
308 without any warranty.
309
311 aklog(1), kafs(3), pam(7), syslog(3), unlog(1)
3122.6 2015-09-19 PAM_AFS_SESSION(5)