1PAM_KRB5(5) pam-krb5 PAM_KRB5(5)
2
6 pam_krb5 - Kerberos PAM module
7
9 auth sufficient pam_krb5.so minimum_uid=1000
10 session required pam_krb5.so minimum_uid=1000
11 account required pam_krb5.so minimum_uid=1000
12 password sufficient pam_krb5.so minimum_uid=1000
13
15 The Kerberos service module for PAM, typically installed at
16 /$LIB/security/pam_krb5.so, provides functionality for the four PAM
17 operations: authentication, account management, session management, and
18 password management. pam_krb5.so is a shared object that is
19 dynamically loaded by the PAM subsystem as necessary, based on the
20 system PAM configuration. PAM is a system for plugging in external
21 authentication and session management modules so that each application
22 doesn't have to know the best way to check user authentication or
23 create a user session on that system. For details on how to configure
24 PAM on your system, see the PAM man page, often pam(7).
25 Here are the actions of this module when called from each group:
27 auth
29 Provides implementations of pam_authenticate() and pam_setcred().
30 The former takes the username from the PAM session, prompts for the
31 user's password (unless configured to use an already-entered
32 password), and then performs a Kerberos initial authentication,
33 storing the obtained credentials (if successful) in a temporary
34 ticket cache. The latter, depending on the flags it is called
35 with, either takes the contents of the temporary ticket cache and
36 writes it out to a persistent ticket cache owned by the user or
37 uses the temporary ticket cache to refresh an existing user ticket
38 cache.
39 Passwords as long or longer than PAM_MAX_RESP_SIZE octets (normally
41 512 octets) will be rejected, since excessively long passwords can
42 be used as a denial of service attack.
43 After doing the initial authentication, the Kerberos PAM module
45 will attempt to obtain tickets for a key in the local system keytab
46 and then verify those tickets. Unless this step is performed, the
47 authentication is vulnerable to KDC spoofing, but it requires that
48 the system have a local key and that the PAM module be running as a
49 user that can read the keytab file (normally /etc/krb5.keytab. You
50 can point the Kerberos PAM module at a different keytab with the
51 keytab option. If that keytab cannot be read or if no keys are
52 found in it, the default (potentially insecure) behavior is to skip
53 this check. If you want to instead fail authentication if the
54 obtained tickets cannot be checked, set "verify_ap_req_nofail" to
55 true in the [libdefaults] section of /etc/krb5.conf. Note that
56 this will affect applications other than this PAM module.
57 By default, whenever the user is authenticated, a basic
59 authorization check will also be done using krb5_kuserok(). The
60 default behavior of this function is to check the user's account
61 for a .k5login file and, if one is present, ensure that the user's
62 principal is listed in that file. If .k5login is not present, the
63 default check is to ensure that the user's principal is in the
64 default local realm and the user portion of the principal matches
65 the account name (this can be changed by configuring a custom aname
66 to localname mapping in krb5.conf; see the Kerberos documentation
67 for details). This can be customized with several configuration
68 options; see below.
69 If the username provided to PAM contains an "@" and Kerberos can,
71 treating the username as a principal, map it to a local account
72 name, pam_authenticate() will change the PAM user to that local
73 account name. This allows users to log in with their Kerberos
74 principal and let Kerberos do the mapping to an account. This can
75 be disabled with the no_update_user option. Be aware, however,
76 that this facility cannot be used with OpenSSH. OpenSSH will
77 reject usernames that don't match local accounts before this
78 remapping can be done and will pass an invalid password to the PAM
79 module. Also be aware that several other common PAM modules, such
80 as pam_securetty, expect to be able to look up the user with
81 getpwnam() and cannot be called before pam_krb5 when using this
82 feature.
83 When pam_setcred() is called to initialize a new ticket cache, the
85 environment variable KRB5CCNAME is set to the path to that ticket
86 cache. By default, the cache will be named /tmp/krb5cc_UID_RANDOM
87 where UID is the user's UID and RANDOM is six randomly-chosen
88 letters. This can be configured with the ccache and ccache_dir
89 options.
90 pam-krb5 does not use the default ticket cache location or
92 default_cc_name in the "[libdefaults]" section of krb5.conf. The
93 default cache location would share a cache for all sessions of the
94 same user, which causes confusing behavior when the user logs out
95 of one of multiple sessions.
96 If pam_setcred() initializes a new ticket cache, it will also set
98 up that ticket cache so that it will be deleted when the PAM
99 session is closed. Normally, the calling program (login, sshd,
100 etc.) will run the user's shell as a sub-process, wait for it to
101 exit, and then close the PAM session, thereby cleaning up the
102 user's session.
103 session
105 Provides implementations of pam_open_session(), which is equivalent
106 to calling pam_setcred() with the PAM_ESTABLISH_CRED flag, and
107 pam_close_session(), which destroys the ticket cache created by
108 pam_setcred().
109 account
111 Provides an implementation of pam_acct_mgmt(). All it does is do
112 the same authorization check as performed by the pam_authenticate()
113 implementation described above.
114 password
116 Provides an implementation of pam_chauthtok(), which implements
117 password changes. The user is prompted for their existing password
118 (unless configured to use an already entered one) and the PAM
119 module then obtains credentials for the special Kerberos principal
120 "kadmin/changepw". It then prompts the user for a new password,
121 twice to ensure that the user entered it properly (again, unless
122 configured to use an already entered password), and then does a
123 Kerberos password change.
124 Passwords as long or longer than PAM_MAX_RESP_SIZE octets (normally
126 512 octets) will be rejected, since excessively long passwords can
127 be used as a denial of service attack.
128 Unlike the normal Unix password module, this module will allow any
130 user to change any other user's password if they know the old
131 password. Also, unlike the normal Unix password module, root will
132 always be prompted for the old password, since root has no special
133 status in Kerberos. (To change passwords in Kerberos without
134 knowing the old password, use kadmin(8) instead.)
135 Both the account and session management calls of the Kerberos PAM
137 module will return PAM_IGNORE if called in the context of a PAM session
138 for a user who did not authenticate with Kerberos (a return code of
139 "ignore" in the Linux PAM configuration language).
140 Note that this module assumes the network is available in order to do a
142 Kerberos authentication. If the network is not available, some
143 Kerberos libraries have timeouts longer than the timeout imposed by the
144 login process. This means that using this module incautiously can make
145 it impossible to log on to console as root. For this reason, you
146 should always use the ignore_root or minimum_uid options, list a local
147 authentication module such as pam_unix first with a control field of
148 "sufficient" so that the Kerberos PAM module will be skipped if local
149 password authentication was successful.
150 This is not the same PAM module as the Kerberos PAM module available
152 from Sourceforge, or the one included on Red Hat systems. It supports
153 many of the same options, has some additional options, and doesn't
154 support some of the options those modules do.
155
157 The Kerberos PAM module takes many options, not all of which are
158 relevant to every PAM group; options that are not relevant will be
159 silently ignored. Any of these options can be set in the PAM
160 configuration as arguments listed after "pam_krb5.so". Some of the
161 options can also be set in the system krb5.conf file; if this is
162 possible, it will be noted below in the option description.
163 To set a boolean option in the PAM configuration file, just give the
165 name of the option in the arguments. To set an option that takes an
166 argument, follow the option name with an equal sign (=) and the value,
167 with no separating whitespace. Whitespace in option arguments is not
168 supported in the PAM configuration.
169 To set an option for the PAM module in the system krb5.conf file, put
171 that option in the "[appdefaults]" section. All options must be
172 followed by an equal sign (=) and a value, so for boolean options add
173 "= true". The Kerberos PAM module will look for options either at the
174 top level of the "[appdefaults]" section or in a subsection named
175 "pam", inside or outside a section for the realm. For example, the
176 following fragment of a krb5.conf file would set forwardable to true,
177 minimum_uid to 1000, and set ignore_k5login only if the realm is
178 EXAMPLE.COM.
179 [appdefaults]
181 forwardable = true
182 pam = {
183 minimum_uid = 1000
184 EXAMPLE.COM = {
185 ignore_k5login = true
186 }
187 }
188 For more information on the syntax of krb5.conf, see krb5.conf(5).
190 Note that options that depend on the realm will be set only on the
191 basis of the default realm, either as configured in krb5.conf(5) or as
192 set by the realm option described below. If the user authenticates to
193 an account qualified with a realm, that realm will not be used when
194 determining which options will apply.
195 There is no difference to the PAM module whether options are specified
197 at the top level or in a "pam" section; the "pam" section is supported
198 in case there are options that should be set for the PAM module but not
199 for other applications.
200 If the same option is set in krb5.conf and in the PAM configuration,
202 the latter takes precedent. Note, however, that due to the
203 configuration syntax, there's no way to turn off a boolean option in
204 the PAM configuration that was turned on in krb5.conf.
205 The start of each option description is annotated with the version of
207 pam-krb5 in which that option was added with the current meaning.
208 Authorization
210 alt_auth_map=<format>
211 [3.12] This functions similarly to the search_k5login option. The
212 <format> argument is used as the authentication Kerberos principal,
213 with any %s in <format> replaced with the username. If the
214 username contains an "@", only the part of the username before the
215 realm is used to replace %s. If <format> contains a realm, it will
216 be used; otherwise, the realm of the username (if any) will be
217 appended to the result. There is no quote removal.
218 If this option is present, the default behavior is to try this
220 alternate principal first and then fall back to the standard
221 behavior if it fails. The primary usage is to allow alternative
222 principals to be used for authentication in programs like sudo.
223 Most examples will look like:
224 alt_auth_map=%s/root
226 which attempts authentication as the root instance of the username
228 first and then falls back to the regular username (but see
229 force_alt_auth and only_alt_auth).
230 This option also allows a cheap way to attempt authentication in an
232 alternative realm first and then fall back to the primary realm. A
233 setting like:
234 alt_auth_map=%s@EXAMPLE.COM
236 will attempt authentication in the EXAMPLE.COM realm first and then
238 fall back on the local default realm. This is more convenient than
239 running the module multiple times with multiple default realms set
240 with realm, but it is very limited: only two realms can be tried,
241 and the alternate realm is always tried first.
242 This option can be set in "[appdefaults]" in krb5.conf, although
244 normally it doesn't make sense to do that; normally it is used in
245 the PAM options of configuration for specific programs. It is only
246 applicable to the auth and account groups. If this option is set
247 for the auth group, be sure to set it for the account group as well
248 or account authorization may fail.
249 force_alt_auth
251 [3.12] This option is used with alt_auth_map and forces
252 authentication as the mapped principal if that principal exists in
253 the KDC. Only if the KDC returns principal unknown does the
254 Kerberos PAM module fall back to normal authentication. This can
255 be used to force authentication with an alternate instance. If
256 alt_auth_map is not set, it has no effect.
257 This option can be set in "[appdefaults]" in krb5.conf and is only
259 applicable to the auth group.
260 ignore_k5login
262 [2.0] Never look for a .k5login file in the user's home directory.
263 Instead, only check that the Kerberos principal maps to the local
264 account name. The default check is to ensure the realm matches the
265 local realm and the user portion of the principal matches the local
266 account name, but this can be customized by setting up an aname to
267 localname mapping in krb5.conf.
268 This option can be set in "[appdefaults]" in krb5.conf and is only
270 applicable to the auth and account groups.
271 ignore_root
273 [1.1] Do not do anything if the username is "root". The
274 authentication and password calls will silently fail (allowing that
275 status to be ignored via a control of "optional" or "sufficient"),
276 and the account and session calls (including pam_setcred) will
277 return PAM_IGNORE, telling the PAM library to proceed as if they
278 weren't mentioned in the PAM configuration. This option is
279 supported and will remain, but normally you want to use minimum_uid
280 instead.
281 This option can be set in "[appdefaults]" in krb5.conf.
283 minimum_uid=<uid>
285 [2.0] Do not do anything if the authenticated account name
286 corresponds to a local account and that local account has a UID
287 lower than <uid>. If both of those conditions are true, the
288 authentication and password calls will silently fail (allowing that
289 status to be ignored via a control of "optional" or "sufficient"),
290 and the account and session calls (including pam_setcred) will
291 return PAM_IGNORE, telling the PAM library to proceed as if they
292 weren't mentioned in the PAM configuration.
293 Using this option is highly recommended if you don't need to use
295 Kerberos to authenticate password logins to the root account (which
296 isn't recommended since Kerberos requires a network connection).
297 It provides some defense in depth against user principals that
298 happen to match a system account incorrectly authenticating as that
299 system account.
300 This option can be set in "[appdefaults]" in krb5.conf.
302 only_alt_auth
304 [3.12] This option is used with alt_auth_map and forces the use of
305 the mapped principal for authentication. It disables fallback to
306 normal authentication in all cases and overrides search_k5login and
307 force_alt_auth. If alt_auth_map is not set, it has no effect and
308 the standard authentication behavior is used.
309 This option can be set in "[appdefaults]" in krb5.conf and is only
311 applicable to the auth group.
312 search_k5login
314 [2.0] Normally, the Kerberos implementation of pam_authenticate
315 attempts to obtain tickets for the authenticating username in the
316 local realm. If this option is set and the local user has a
317 .k5login file in their home directory, the module will instead open
318 and read that .k5login file, attempting to use the supplied
319 password to authenticate as each principal listed there in turn.
320 If any of those authentications succeed, the user will be
321 successfully authenticated; otherwise, authentication will fail.
322 This option is useful for allowing password authentication (via
323 console or sshd without GSS-API support) to shared accounts. If
324 there is no .k5login file, the behavior is the same as normal.
325 Using this option requires that the user's .k5login file be
326 readable at the time of authentication.
327 This option can be set in "[appdefaults]" in krb5.conf and is only
329 applicable to the auth group.
330 Kerberos Behavior
332 anon_fast
333 [4.6] Attempt to use Flexible Authentication Secure Tunneling
334 (FAST) by first authenticating as the anonymous user
335 (WELLKNOWN/ANONYMOUS) and using its credentials as the FAST armor.
336 This requires anonymous PKINIT be enabled for the local realm, that
337 PKINIT be configured on the local system, and that the Kerberos
338 library support FAST and anonymous PKINIT.
339 FAST is a mechanism to protect Kerberos against password guessing
341 attacks and provide other security improvements. To work, FAST
342 requires that a ticket be obtained with a strong key to protect
343 exchanges with potentially weaker user passwords. This option uses
344 anonymous authentication to obtain that key and then uses it to
345 protect the subsequent authentication.
346 If anonymous PKINIT is not available or fails, FAST will not be
348 used and the authentication will proceed as normal.
349 To instead use an existing ticket cache for the FAST credentials,
351 use fast_ccache instead of this option. If both fast_ccache and
352 anon_fast are set, the ticket cache named by fast_ccache will be
353 tried first, and the Kerberos PAM module will fall back on
354 attempting anonymous PKINIT if that cache could not be used.
355 This option can be set in "[appdefaults]" in krb5.conf and is only
357 applicable to the auth and password groups.
358 The operation is the same as if using the fast_ccache option, but
360 the cache is created and destroyed automatically. If both
361 fast_ccache and anon_fast options are used, the fast_ccache takes
362 precedent and no anonymous authentication is done.
363 fast_ccache=<ccache_name>
365 [4.3] The same as anon_fast, but use an existing Kerberos ticket
366 cache rather than anonymous PKINIT. This allows use of FAST with a
367 realm that doesn't support PKINIT or doesn't support anonymous
368 authentication.
369 <ccache_name> should be a credential cache containing a ticket
371 obtained using a strong key, such as the randomized key for the
372 host principal of the local system. If <ccache_name> names a
373 ticket cache that is readable by the authenticating process and has
374 tickets then FAST will be attempted. The easiest way to use this
375 option is to use a program like k5start to maintain a ticket cache
376 using the host's keytab. This ticket cache should normally only be
377 readable by root, so this option will not be able to protect
378 authentications done as non-root users (such as screensavers).
379 If no credentials are present in the ticket cache, or if the ticket
381 cache does not exist or is not readable, FAST will not used and
382 authentication will proceed as normal. However, if the credentials
383 in that ticket cache are expired, authentication will fail if the
384 KDC supports FAST.
385 To use anonymous PKINIT to protect the FAST exchange, use the
387 anon_fast option instead. anon_fast is easier to configure, since
388 no existing ticket cache is required, but requires PKINIT be
389 available and configured and that the local realm support anonymous
390 authentication. If both fast_ccache and anon_fast are set, the
391 ticket cache named by fast_ccache will be tried first, and the
392 Kerberos PAM module will fall back on attempting anonymous PKINIT
393 if that cache could not be used.
394 This option can be set in "[appdefaults]" in krb5.conf and is only
396 applicable to the auth and password groups.
397 forwardable
399 [1.0] Obtain forwardable tickets. If set (to either true or false,
400 although it can only be set to false in krb5.conf), this overrides
401 the Kerberos library default set in the [libdefaults] section of
402 krb5.conf.
403 This option can be set in "[appdefaults]" in krb5.conf and is only
405 applicable to the auth group.
406 keytab=<path>
408 [3.0] Specifies the keytab to use when validating the user's
409 credentials. The default is the default system keytab (normally
410 /etc/krb5.keytab), which is usually only readable by root.
411 Applications not running as root that use this PAM module for
412 authentication may wish to point it to another keytab the
413 application can read. The first principal found in the keytab will
414 be used as the principal for credential verification.
415 This option can be set in "[appdefaults]" in krb5.conf and is only
417 applicable to the auth group.
418 realm=<realm>
420 [2.2] Set the default Kerberos realm and obtain credentials in that
421 realm, rather than in the normal default realm for this system. If
422 this option is used, it should be set for all groups being used for
423 consistent results. This setting will affect authorization
424 decisions since it changes the default realm. This setting will
425 also change the service principal used to verify the obtained
426 credentials to be in the specified realm.
427 If you only want to set the realm assumed for user principals
429 without changing the realm for authorization decisions or the
430 service principal used to verify credentials, see the user_realm
431 option.
432 renew_lifetime=<lifetime>
434 [2.0] Obtain renewable tickets with a maximum renewable lifetime of
435 <lifetime>. <lifetime> should be a Kerberos lifetime string such
436 as "2d4h10m" or a time in minutes. If set, this overrides the
437 Kerberos library default set in the [libdefaults] section of
438 krb5.conf.
439 This option can be set in "[appdefaults]" in krb5.conf and is only
441 applicable to the auth group.
442 ticket_lifetime=<lifetime>
444 [3.0] Obtain tickets with a maximum lifetime of <lifetime>.
445 <lifetime> should be a Kerberos lifetime string such as "2d4h10m"
446 or a time in minutes. If set, this overrides the Kerberos library
447 default set in the [libdefaults] section of krb5.conf.
448 This option can be set in "[appdefaults]" in krb5.conf and is only
450 applicable to the auth group.
451 user_realm
453 [4.6] Obtain credentials in the specified realm rather than in the
454 default realm for this system. If this option is used, it should
455 be set for all groups being used for consistent results (although
456 the account group currently doesn't care about realm). This will
457 not change authorization decisions. If the obtained credentials
458 are supposed to allow access to a shell account, the user will need
459 an appropriate .k5login file entry or the system will have to have
460 a custom aname_to_localname mapping.
461 PAM Behavior
463 clear_on_fail
464 [3.9] When changing passwords, PAM first does a preliminary check
465 through the complete password stack, and then calls each module
466 again to do the password change. After that preliminary check, the
467 order of module invocation is fixed. This means that even if the
468 Kerberos password change fails (or if one of the other password
469 changes in the stack fails), other password PAM modules in the
470 stack will still be called even if the failing module is marked
471 required or requisite. When using multiple password PAM modules to
472 synchronize passwords between multiple systems when they change,
473 this behavior can cause unwanted differences between the
474 environments.
475 Setting this option provides a way to work around this behavior.
477 If this option is set and a Kerberos password change is attempted
478 and fails (due to network errors or password strength checking on
479 the KDC, for example), this module will clear the stored password
480 in the PAM stack. This will force any subsequent modules that have
481 use_authtok set to fail so that those environments won't get out of
482 sync with the password in Kerberos. The Kerberos PAM module will
483 not meddle with the stored password if it skips the user due to
484 configuration such as minimum_uid.
485 Unfortunately, setting this option interferes with other desirable
487 PAM configurations, such as attempting to change the password in
488 Kerberos first and falling back on the local Unix password database
489 if that fails. It therefore isn't the default. Turn it on (and
490 list pam_krb5 first after pam_cracklib if used) when synchronizing
491 passwords between multiple environments.
492 This option can be set in "[appdefaults]" in krb5.conf and is only
494 applicable to the password group.
495 debug
497 [1.0] Log more verbose trace and debugging information to syslog at
498 LOG_DEBUG priority, including entry and exit from each of the
499 external PAM interfaces (except pam_close_session).
500 This option can be set in "[appdefaults]" in krb5.conf.
502 defer_pwchange
504 [3.11] By default, pam-krb5 lets the Kerberos library handle
505 prompting for a password change if an account's password is expired
506 during the auth group. If this fails, pam_authenticate() returns
507 an error.
508 According to the PAM standard, this is not the correct way to
510 handle expired passwords. Instead, pam_authenticate() should
511 return success without attempting a password change, and then
512 pam_acct_mgmt() should return PAM_NEW_AUTHTOK_REQD, at which point
513 the calling application is responsible for either rejecting the
514 authentication or calling pam_chauthtok(). However, following the
515 standard requires that all applications call pam_acct_mgmt() and
516 check its return status; otherwise, expired accounts may be able to
517 successfully authenticate. Many applications do not do this.
518 If this option is set, pam-krb5 uses the fully correct PAM
520 mechanism for handling expired accounts instead of failing in
521 pam_authenticate(). Due to the security risk of widespread broken
522 applications, be very careful about enabling this option. It
523 should normally only be turned on to solve a specific problem (such
524 as using Solaris Kerberos libraries that don't support prompting
525 for password changes during authentication), and then only for
526 specific applications known to call pam_acct_mgmt() and check its
527 return status properly.
528 This option is only supported when pam-krb5 is built with MIT
530 Kerberos. If built against Heimdal, this option does nothing and
531 normal expired password change handling still happens. (Heimdal is
532 missing the required API to implement this option, at least as of
533 version 1.6.)
534 This option can be set in "[appdefaults]" in krb5.conf and is only
536 applicable to the auth group.
537 fail_pwchange
539 [4.2] By default, pam-krb5 lets the Kerberos library handle
540 prompting for a password change if an account's password is expired
541 during the auth group. If this option is set, expired passwords
542 are instead treated as an authentication failure identical to an
543 incorrect password. Also see defer_pwchange and force_pwchange.
544 This option can be set in "[appdefaults]" in krb5.conf and is only
546 applicable to the auth group.
547 force_pwchange
549 [3.11] If this option is set and authentication fails with a
550 Kerberos error indicating the user's password is expired, attempt
551 to immediately change their password during the authenticate step.
552 Under normal circumstances, this is unnecessary. Most Kerberos
553 libraries will do this for you, and setting this option will prompt
554 the user twice to change their password if the first attempt (done
555 by the Kerberos library) fails. However, some system Kerberos
556 libraries (such as Solaris's) have password change prompting
557 disabled in the Kerberos library; on those systems, you can set
558 this option to simulate the normal library behavior.
559 This option can be set in "[appdefaults]" in krb5.conf and is only
561 applicable to the auth group.
562 no_update_user
564 [4.7] Normally, if pam-krb5 is able to canonicalize the principal
565 to a local name using krb5_aname_to_localname() or similar calls,
566 it changes the PAM_USER variable for this PAM session to the
567 canonicalized local name. Setting this option disables this
568 behavior and leaves PAM_USER set to the initial authentication
569 identity.
570 This option can be set in "[appdefaults]" in krb5.conf and is only
572 applicable to the auth group.
573 silent
575 [1.0] Don't show messages and errors from Kerberos, such as
576 warnings of expiring passwords, to the user via the prompter. This
577 is equivalent to the behavior when the application passes in
578 PAM_SILENT, but can be set in the PAM configuration.
579 This option is only applicable to the auth and password groups.
581 trace=<log-file>
583 [4.6] Enables Kerberos library trace logging to the specified log
584 file if it is supported by the Kerberos library. This is intended
585 for temporary debugging. The specified file will be appended to
586 without further security checks, so do not specify a file in a
587 publicly writable directory like /tmp.
588 PKINIT
590 pkinit_anchors=<anchors>
591 [3.0] When doing PKINIT authentication, use <anchors> as the client
592 trust anchors. This is normally a reference to a file containing
593 the trusted certificate authorities. This option is only used if
594 try_pkinit or use_pkinit are set.
595 This option can be set in "[appdefaults]" in krb5.conf and is only
597 applicable to the auth and password groups.
598 pkinit_prompt
600 [3.0] Before attempting PKINIT authentication, prompt the user to
601 insert a smart card. You may want to set this option for programs
602 such as gnome-screensaver that call PAM as soon as the mouse is
603 touched and don't give the user an opportunity to enter the smart
604 card first. Any information entered at the first prompt is
605 ignored. If try_pkinit is set, a user who wishes to use a password
606 instead can just press Enter and then enter their password as
607 normal. This option is only used if try_pkinit or use_pkinit are
608 set.
609 This option can be set in "[appdefaults]" in krb5.conf and is only
611 applicable to the auth and password groups.
612 pkinit_user=<userid>
614 [3.0] When doing PKINIT authentication, use <userid> as the user
615 ID. The value of this string is highly dependent on the type of
616 PKINIT implementation you're using, but will generally be something
617 like:
618 PKCS11:/usr/$LIB/pkcs11/$LIB/soft-pkcs11.so
620 to specify the module to use with a smart card. It may also point
622 to a user certificate or to other types of user IDs. See the
623 Kerberos library documentation for more details. This option is
624 only used if try_pkinit or use_pkinit are set.
625 This option can be set in "[appdefaults]" in krb5.conf and is only
627 applicable to the auth and password groups.
628 preauth_opt=<option>
630 [3.3] Sets a preauth option (currently only applicable when built
631 with MIT Kerberos). <option> is either a key/value pair with the
632 key separated from the value by "=" or a boolean option (in which
633 case it's turned on). In krb5.conf, multiple options should be
634 separated by whitespace. In the PAM configuration, this option can
635 be given multiple times to set multiple options. In either case,
636 <option> may not contain whitespace.
637 The primary use of this option, at least in the near future, will
639 be to set options for the MIT Kerberos PKINIT support. For the
640 full list of possible options, see the PKINIT plugin documentation.
641 At the time of this writing, "X509_user_identity" is equivalent to
642 pkinit_user and "X509_anchors" is equivalent to pkinit_anchors.
643 "flag_DSA_PROTOCOL" can only be set via this option.
644 Any settings made with this option are applied after the
646 pkinit_anchors and pkinit_user options, so if an equivalent setting
647 is made via preauth_opt, it will probably override the other
648 setting.
649 This option can be set in "[appdefaults]" in krb5.conf and is only
651 applicable to the auth and password groups. Note that there is no
652 way to remove a setting made in krb5.conf using the PAM
653 configuration, but options set in the PAM configuration are applied
654 after options set in krb5.conf and therefore may override earlier
655 settings.
656 try_pkinit
658 [3.0] Attempt PKINIT authentication before trying a regular
659 password. You will probably also need to set the pkinit_user
660 configuration option. If PKINIT fails, the PAM module will fall
661 back on regular password authentication. This option is currently
662 only supported if pam-krb5 was built against Heimdal 0.8rc1 or
663 later or MIT Kerberos 1.6.3 or later.
664 If this option is set and pam-krb5 is built against MIT Kerberos,
666 and PKINIT fails and the module falls back to password
667 authentication, the user's password will not be stored in the PAM
668 stack for subsequent modules. This is a bug in the interaction
669 between the module and MIT Kerberos that requires some reworking of
670 the PKINIT authentication method to fix.
671 This option can be set in "[appdefaults]" in krb5.conf and is only
673 applicable to the auth and password groups.
674 use_pkinit
676 [3.0, 4.9 for MIT Kerberos] Require PKINIT authentication. You
677 will probably also need to set the pkinit_user configuration
678 option. If PKINIT fails, authentication will fail. This option is
679 only supported if pam-krb5 was built against Heimdal 0.8rc1 or
680 later or MIT Kerberos 1.12 or later.
681 Be aware that, with MIT Kerberos, this option is implemented by
683 using a responder without a prompter, and thus any informational
684 messages from the Kerberos libraries or KDC during authentication
685 will not be displayed.
686 This option can be set in "[appdefaults]" in krb5.conf and is only
688 applicable to the auth and password groups.
689 Prompting
691 banner=<banner>
692 [3.0] By default, the prompts when a user changes their password
693 are:
694 Current Kerberos password:
696 Enter new Kerberos password:
697 Retype new Kerberos password:
698 The string "Kerberos" is inserted so that users aren't confused
700 about which password they're changing. Setting this option
701 replaces the word "Kerberos" with whatever this option is set to.
702 Setting this option to the empty string removes the word before
703 "password:" entirely.
704 If set in the PAM configuration, <banner> may not contain
706 whitespace. If you want a value containing whitespace, set it in
707 krb5.conf.
708 This option can be set in "[appdefaults]" in krb5.conf and is only
710 applicable to the password group.
711 expose_account
713 [3.0] By default, the Kerberos PAM module password prompt is simply
714 "Password:". This avoids leaking any information about the system
715 realm or account to principal conversions. If this option is set,
716 the string "for <principal>" is added before the colon, where
717 <principal> is the user's principal. This string is also added
718 before the colon on prompts when changing the user's password.
719 Enabling this option with ChallengeResponseAuthentication enabled
721 in OpenSSH may cause problems for some ssh clients that only
722 recognize "Password:" as a prompt. This option is automatically
723 disabled if search_k5login is enabled since the principal displayed
724 would be inaccurate.
725 This option can be set in "[appdefaults]" in krb5.conf and is only
727 applicable to the auth and password groups.
728 force_first_pass
730 [4.0] Use the password obtained by a previous authentication or
731 password module to authenticate the user without prompting the user
732 again. If no previous module obtained the user's password, fail
733 without prompting the user. Also see try_first_pass and
734 use_first_pass for weaker versions of this option.
735 This option is only applicable to the auth and password groups.
737 For the password group, it applies only to the old password. See
738 use_authtok for a similar setting for the new password.
739 no_prompt
741 [4.6] Never prompt for the current password. Instead, pass in a
742 NULL password to the Kerberos library and let the Kerberos library
743 do the prompting. This may be needed if, for example, the Kerberos
744 library is configured to use other authentication mechanisms than
745 passwords and needs full control over the prompting process.
746 The major disadvantage of this option is that it means the PAM
748 module will never see the user's password and therefore cannot save
749 it in the PAM module data for any subsequent modules. In other
750 words, this option cannot be used if another module is in the stack
751 behind the Kerberos PAM module and wants to use use_first_pass.
752 The Kerberos library also usually includes the principal in the
753 prompt, and therefore this option implies behavior similar to
754 expose_account. Similar to expose_account, this can cause problems
755 with OpenSSH if ChallengeResponseAuthentication is enabled, since
756 clients may not recognize password prompts other than "Password:".
757 Using this option with search_k5login would result in a password
759 prompt for every principal listed in the user's .k5login file.
760 This is probably not desired behavior, although it's not prohibited
761 by the module.
762 This option is only applicable to the auth and password groups.
764 For the password group, it applies only to the authentication
765 process; the user will still be prompted for a new password.
766 prompt_principal
768 [3.6] Before prompting for the user's password (or using the
769 previously entered password, if try_first_pass, use_first_pass, or
770 force_first_pass are set), prompt the user for the Kerberos
771 principal to use for authentication. This allows the user to
772 authenticate with a different principal than the one corresponding
773 to the local username, provided that either a .k5login file or
774 local Kerberos principal to account mapping authorize that
775 principal to access the local account.
776 Be cautious when using this configuration option and don't use it
778 with OpenSSH PasswordAuthentication, only
779 ChallengeResponseAuthentication. Some PAM-enabled applications
780 expect PAM modules to only prompt for passwords and may even
781 blindly give the password to the first prompt, no matter what it
782 is. Such applications, in combination with this option, may expose
783 the user's password in log messages and Kerberos requests.
784 try_first_pass
786 [1.0] If the authentication module isn't the first on the stack,
787 and a previous module obtained the user's password, use that
788 password to authenticate the user without prompting them again. If
789 that authentication fails, fall back on prompting the user for
790 their password. This option has no effect if the authentication
791 module is first in the stack or if no previous module obtained the
792 user's password. Also see use_first_pass and force_first_pass for
793 stronger versions of this option.
794 This option is only applicable to the auth and password groups.
796 For the password group, it applies only to the old password.
797 use_authtok
799 [4.0] Use the new password obtained by a previous password module
800 when changing passwords rather than prompting for the new password.
801 If the new password isn't available, fail. This can be used to
802 require passwords be checked by another, prior module, such as
803 pam_cracklib.
804 This option is only applicable to the password group.
806 use_first_pass
808 [1.0] Use the password obtained by a previous authentication module
809 to authenticate the user without prompting the user again. If no
810 previous module obtained the user's password for either an
811 authentication or password change, fall back on prompting the user.
812 If a previous module did obtain the user's password but
813 authentication with that password fails, fail without further
814 prompting the user. Also see try_first_pass and force_first_pass
815 for other versions of this option.
816 This option is only applicable to the auth and password groups.
818 For the password group, it applies only to the old password. See
819 use_authtok for a similar setting for the new password.
820 Ticket Caches
822 ccache=<pattern>
823 [2.0] Use <pattern> as the pattern for creating credential cache
824 names. <pattern> must be in the form <type>:<residual> where
825 <type> and the following colon are optional if a file cache should
826 be used. The special token %u, anywhere in <pattern>, is replaced
827 with the user's numeric UID. The special token %p, anywhere in
828 <pattern>, is replaced with the current process ID.
829 If <pattern> ends in the literal string "XXXXXX" (six X's), that
831 string will be replaced by randomly generated characters and the
832 ticket cache will be created using mkstemp(3). This is strongly
833 recommended if <pattern> points to a world-writable directory.
834 This option can be set in "[appdefaults]" in krb5.conf and is only
836 applicable to the auth and session groups.
837 ccache_dir=<directory>
839 [1.2] Store both the temporary ticket cache used during
840 authentication and user ticket caches in <directory> instead of in
841 /tmp. The algorithm for generating the ticket cache name is
842 otherwise unchanged. <directory> may be prefixed with "FILE:" to
843 make the cache type unambiguous (and this may be required on
844 systems that use a cache type other than file as the default).
845 Be aware that pam_krb5 creates and stores a temporary ticket cache
847 file owned by root during the login process. If you set ccache
848 above to avoid using the system /tmp directory for user ticket
849 caches, you may also want to set ccache_dir to move those temporary
850 caches to some other location. This will allow pam_krb5 to
851 continue working even if the system /tmp directory is full.
852 This option can be set in "[appdefaults]" in krb5.conf and is only
854 applicable to the auth and session groups.
855 no_ccache
857 [1.0] Do not create a ticket cache after authentication. This
858 option shouldn't be set in general, but is useful as part of the
859 PAM configuration for a particular service that uses PAM for
860 authentication but isn't creating user sessions and doesn't want
861 the overhead of ever writing the user credentials to disk. When
862 using this option, the application should only call
863 pam_authenticate(); other functions like pam_setcred(),
864 pam_start_session(), and pam_acct_mgmt() don't make sense with this
865 option. Don't use this option if the application needs PAM account
866 and session management calls.
867 This option is only applicable to the auth group.
869 retain_after_close
871 [2.3] Normally, the user's ticket cache is destroyed when either
872 pam_end() or pam_close_session() is called by the authenticating
873 application so that ticket caches aren't left behind after the user
874 logs out. In some cases, however, this isn't desirable. (On
875 Solaris 8, for instance, the default behavior means login will
876 destroy the ticket cache before running the user's shell.) If this
877 option is set, the PAM module will never destroy the user's ticket
878 cache. If you set this, you may want to call kdestroy in the
879 shell's logout configuration or run a temporary file removal
880 program to avoid accumulating hundreds of ticket caches in /tmp.
881 This option can be set in "[appdefaults]" in krb5.conf and is only
883 applicable to the auth and session groups.
884
886 KRB5CCNAME
887 Set by pam_setcred() with the PAM_ESTABLISH_CRED option, and
888 therefore also by pam_open_session(), to point to the new
889 credential cache for the user. See the ccache and ccache_dir
890 options. By default, the cache name will be prefixed with "FILE:"
891 to make the cache type unambiguous.
892 PAM_KRB5CCNAME
894 Set by pam_authenticate() to point to the temporary ticket cache
895 used for authentication (unless the no_ccache option was given).
896 pam_setcred() then uses that environment variable to locate the
897 temporary cache even if it was not called in the same PAM session
898 as pam_authenticate() (a problem with sshd running in some modes).
899 This environment variable is only used internal to the PAM module.
900
902 /tmp/krb5cc_UID_RANDOM
903 The default credential cache name. UID is the decimal UID of the
904 local user and RANDOM is a random six-character string. The
905 pattern may be changed with the ccache option and the directory
906 with the ccache_dir option.
907 /tmp/krb5cc_pam_RANDOM
909 The credential cache name used for the temporary credential cache
910 created by pam_authenticate(). This cache is removed again when
911 the PAM session is ended or when pam_setcred() is called and will
912 normally not be user-visible. RANDOM is a random six-character
913 string.
914 ~/.k5login
916 File containing Kerberos principals that are allowed access to that
917 account.
918
920 If try_pkinit is set and pam-krb5 is built with MIT Kerberos, the
921 user's password is not saved in the PAM data if PKINIT fails and the
922 module falls back to password authentication.
923
925 Be sure to list this module in the session group as well as the auth
926 group when using it for interactive logins. Otherwise, some
927 applications (such as OpenSSH) will not set up the user's ticket cache
928 correctly.
929 The Kerberos library, via pam-krb5, will prompt the user to change
931 their password if their password is expired, but when using OpenSSH,
932 this will only work when ChallengeResponseAuthentication is enabled.
933 Unless this option is enabled, OpenSSH doesn't pass PAM messages to the
934 user and can only respond to a simple password prompt.
935 If you are using MIT Kerberos, be aware that users whose passwords are
937 expired will not be prompted to change their password unless the KDC
938 configuration for your realm in [realms] in krb5.conf contains a
939 master_kdc setting or, if using DNS SRV records, you have a DNS entry
940 for _kerberos-master as well as _kerberos.
941 pam_authenticate() returns failure when called for an ignored account,
943 requiring the system administrator to use "optional" or "sufficient" to
944 ignore the module and move on to the next module. It's arguably more
945 correct to return PAM_IGNORE, which causes the module to be ignored as
946 if it weren't in the configuration, but this increases the risk of
947 inadvertent security holes when listing pam-krb5 as the only
948 authentication module.
949 This module treats the empty password as an authentication failure
951 rather than attempting to use that password to avoid unwanted prompting
952 behavior in the Kerberos libraries. If you have a Kerberos principal
953 that intentionally has an empty password, it won't work with this
954 module.
955 This module will not refresh an existing ticket cache if called with an
957 effective UID or GID different than the real UID or GID, since
958 refreshing an existing ticket cache requires trusting the KRB5CCNAME
959 environment variable and the environment should not be trusted in a
960 setuid context.
961 Old versions of OpenSSH are known to call pam_authenticate followed by
963 pam_setcred(PAM_REINITIALIZE_CRED) without first calling
964 pam_open_session, thereby requesting that an existing ticket cache be
965 renewed (similar to what a screensaver would want) rather than
966 requesting a new ticket cache be created. Since this behavior is
967 indistinguishable at the PAM level from a screensaver, pam-krb5 when
968 used with these old versions of OpenSSH will refresh the ticket cache
969 of the OpenSSH daemon rather than setting up a new ticket cache for the
970 user. The resulting ticket cache will have the correct permissions,
971 but will not be named correctly or referenced in the user's environment
972 and will be overwritten by the next user login. The best solution to
973 this problem is to upgrade OpenSSH. I'm not sure exactly when this
974 problem was fixed, but at the very least OpenSSH 4.3 and later do not
975 exhibit it.
976
978 pam-krb5 was originally written by Frank Cusack. Andres Salomon made
979 extensive modifications, and then Russ Allbery <eagle@eyrie.org>
980 adopted it and made even more extensive modifications. Russ Allbery
981 currently maintains the module.
982
984 Copyright 2005-2010, 2014, 2020 Russ Allbery <eagle@eyrie.org>
985 Copyright 2008-2014 The Board of Trustees of the Leland Stanford Junior
987 University
988 Copying and distribution of this file, with or without modification,
990 are permitted in any medium without royalty provided the copyright
991 notice and this notice are preserved. This file is offered as-is,
992 without any warranty.
993 SPDX-License-Identifier: FSFAP
995
997 kadmin(8), kdestroy(1), krb5.conf(5), pam(7), passwd(1), syslog(3)
998 The current version of this module is available from its web page at
1000 <https://www.eyrie.org/~eagle/software/pam-krb5/>.
10014.11 2021-10-17 PAM_KRB5(5)