1pam_krb5(5) Standards, Environments, and Macros pam_krb5(5)
2
6 pam_krb5 - authentication, account, session, and password management
7 PAM modules for Kerberos V5
8
10 /usr/lib/security/pam_krb5.so.1
11
14 The Kerberos V5 service module for PAM provides functionality for all
15 four PAM modules: authentication, account management, session manage‐
16 ment, and password management. The service module is a shared object
17 that can be dynamically loaded to provide the necessary functionality
18 upon demand. Its path is specified in the PAM configuration file.
19 Kerberos Authentication Module
21 The Kerberos V5 authentication component provides functions to verify
22 the identity of a user, pam_sm_authenticate(), and to manage the Ker‐
23 beros credentials cache, pam_sm_setcred().
24 pam_sm_authenticate() authenticates a user principal through the Ker‐
27 beros authentication service. If the authentication request is success‐
28 ful, the authentication service sends a ticket-granting ticket (TGT)
29 back to the service module, which then verifies that the TGT came from
30 a valid Key Distribution Center (KDC) by attempting to get a service
31 ticket for the local host service. For this to succeed, the local
32 host's keytab file (/etc/krb5/krb5.keytab) must contain the entry for
33 the local host service. For example, in the file host/host‐
34 name.com@REALM, hostname.com is the fully qualified local hostname and
35 REALM is the default realm of the local host as defined in
36 /etc/krb5/krb5.conf. If the host entry is not found in the keytab file,
37 the authentication fails. Administrators may optionally disable this
38 "strict" verification by setting "verify_ap_req_nofail = false" in
39 /etc/krb5/krb5.conf. See krb5.conf(4) for more details on this option.
40 This allows TGT verification to succeed in the absence of a keytab host
41 principal entry.
42 pam_sm_authenticate(3PAM) may be passed the following flag:
45 PAM_DISALLOW_NULL_AUTHTOK
47 This flag is ignored. The Kerberos authentication mechanism will
49 not allow an empty password string by default.
50 pam_sm_setcred() creates and modifies the user's credential cache. This
54 function initializes the user's credential cache, if it does not
55 already exist, and stores the initial credentials for later use by Ker‐
56 berized network applications. The following flags may be set in the
57 flags field. They are best described by their effect on the user's cre‐
58 dential cache.
59 PAM_ESTABLISH_CRED
61 Stores the initial credentials in the user's credential cache so
63 that the user may access Kerberos network services. If a successful
64 authentication pass was made, the new credentials are stored in the
65 credential cache, overwriting any existing credentials that were
66 previously stored. If an unsuccessful authentication pass was made,
67 PAM_CRED_UNAVAIL is returned.
68 PAM_DELETE_CRED
71 This flag has no effect on the credential cache and always returns
73 PAM_SUCCESS. The credential cache is not deleted because there is
74 no accurate method to determine if the credentials are needed by
75 another process. The credential cache may be deleted with the kde‐
76 stroy(1) command.
77 PAM_REINITIALIZE_CRED
80 Deletes the user's existing credential cache, if it exists, and
82 creates a new credential cache. The new credentials are stored in
83 the new cache and the user's ticket lifetime and renewable life
84 time values are reset.
85 PAM_REFRESH_CRED
88 Does not require a previous authentication pass, but if a success‐
90 ful one is made, the new credentials are stored in the credential
91 cache. If a previous authentication pass was not made or was unsuc‐
92 cessful, an attempt to renew the existing credentials is made. Note
93 that this function fails if the user's renewable ticket lifetime is
94 expired.
95 The following options can be passed to the Kerberos V5 authentication
99 module:
100 debug Provides syslog(3C) debugging information at LOG_DEBUG level.
102 nowarn Turns off warning messages.
105 Kerberos V5 Account Management Module
108 The Kerberos account management component provides a function to per‐
109 form account management, pam_sm_acct_mgmt(). This function checks to
110 see if the pam_krb5 authentication module has noted that the user's
111 password has not expired. The following options may be passed in to the
112 Kerberos V5 account management module:
113 debug Provides syslog(3C) debugging information at LOG_DEBUG level
115 nowarn Turns off warning messages. Also, does not query KDC for
118 impending password expiration information used to warn the
119 user.
120 Kerberos V5 Session Management Module
123 The Kerberos V5 session management component provides functions to ini‐
124 tiate pam_sm_open_session() and terminate pam_sm_close_session() Ker‐
125 beros sessions. For Kerberos V5, both pam_sm_open_session and
126 pam_sm_close_session() are null functions, returning PAM_IGNORE.
127 Kerberos V5 Password Management Module
129 The Kerberos V5 password management component provides a function to
130 change passwords, pam_sm_chauthtok(), in the Key Distribution Center
131 (KDC) database. The following flags may be passed to pam_sm_chauth‐
132 tok(3PAM):
133 PAM_CHANGE_EXPIRED_AUTHTOK
135 The password service should only update the user's Kerberos pass‐
137 word if it is expired. Otherwise, this function returns PAM_IGNORE.
138 The default behaviour is to always change the user's Kerberos pass‐
139 word.
140 PAM_PRELIM_CHECK
143 This is a null function that always returns PAM_IGNORE.
145 PAM_UPDATE_AUTHTOK
148 This flag is necessary to change the user's Kerberos password. If
150 this flag is not set, pam_krb5 returns PAM_SYSTEM_ERR.
151 The following option can be passed to the Kerberos V5 password module:
155 debug Provides syslog(3C) debugging information at LOG_DEBUG level.
157
160 The following error codes are returned for pam_sm_authenticate():
161 PAM_AUTH_ERR Authentication failure
163 PAM_BUF_ERR Memory buffer error.
166 PAM_IGNORE The user is "root" and the root key exists in the
169 default keytab.
170 PAM_SUCCESS Successfully obtained Kerberos credentials .
173 PAM_SYSTEM_ERR System error.
176 PAM_USER_UNKNOWN An unknown Kerberos principal was requested.
179 The following error codes are returned for pam_sm_setcred():
183 PAM_AUTH_ERR Authentication failure.
185 PAM_BUF_ERR Memory buffer error.
188 PAM_IGNORE The user is "root" and the root key exists in the
191 default keytab.
192 PAM_SYSTEM_ERR System error.
195 PAM_SUCCESS Successfully modified the Kerberos credential cache.
198 The following error codes are returned for pam_sm_acct_mgmt():
202 PAM_AUTH_ERR Authentication failure.
204 PAM_IGNORE Kerberos service module pam_sm_authenticate()
207 was never called, or the user is "root" and the
208 root key exists in the default keytab.
209 PAM_NEW_AUTHTOK_REQD Obtain new authentication token from the user.
212 PAM_SERVICE_ERR Error in underlying service module.
215 PAM_SUCCESS Kerberos principal account is valid.
218 PAM_SYSTEM_ERR System error.
221 PAM_USER_UNKNOWN An unknown Kerberos principal was requested.
224 The following error code is returned for pam_sm_open_session() and
228 pam_sm_close_session():
229 PAM_IGNORE These two functions are null functions in pam_krb5:
231 The following error codes are returned for pam_sm_chauthtok():
235 PAM_AUTH_ERR Authentication failure.
237 PAM_IGNORE The user has not been authenticated by Kerberos
240 service module pam_sm_authenticate(), or the
241 user is "root" and the root key exists in the
242 default keytab.
243 PAM_NEW_AUTHTOK_REQD User's Kerberos password has expired.
246 PAM_SERVICE_ERR Error in module. At least one input parameter
249 is missing.
250 PAM_SYSTEM_ERR System error.
253 PAM_USER_UNKNOWN An unknown Kerberos principal was requested.
256 PAM_SUCCESS Successfully changed the user's Kerberos pass‐
259 word.
260
263 Example 1 Authenticate Users Through Kerberos as First Choice
264 The following is an excerpt of a sample pam.conf configuration file
267 that authenticates users through the Kerberos authentication service
268 and authenticates through the Unix login only if the Kerberos authenti‐
269 cation fails. This arrangement is helpful when a majority of the users
270 are networked by means of Kerberos and when there are only a few non-
271 Kerberos type user accounts, such as root. The service illustrated
272 below is for dtlogin.
273 dtlogin auth requisite pam_smartcard.so.1
276 dtlogin auth requisite pam_authtok_get.so.1
277 dtlogin auth required pam_dhkeys.so.1
278 dtlogin auth required pam_unix_cred.so.1
279 dtlogin auth sufficient pam_krb5.so.1
280 dtlogin auth required pam_unix_auth.so.1
281 Note that these changes should not be made to the existing krlogin,
285 krsh, and ktelnet service entries. Those services require Kerberos
286 authentication, so using a seemingly sufficient control flag would not
287 provide the necessary functionality for privacy and integrity. There
288 should be no need to change those entries.
289 The following entries check for password expiration when dealing with
293 Kerberos and Unix password aging policies:
294 other account requisite pam_roles.so.1
297 other account required pam_unix_account.so.1
298 other account required pam_krb5.so.1
299 The following entries would change the Kerberos password of the user
303 and continue to change the Unix login password only if the Kerberos
304 password change had failed:
305 other password required pam_dhkeys.so.1
308 other password requisite pam_authtok_get.so.1
309 other password requisite pam_authtok_check.so.1
310 other password sufficient pam_krb5.so.1
311 other password required pam_authtok_store.so.1
312 When changing Kerberos based user's password, use kpasswd(1). When
316 changing a non-Kerberos user's password, it is recommended that the
317 repository is specified (-r) with the passwd(1) command.
318 Example 2 Authenticate Users Through Kerberos Only
321 The following example allows authentication only to users that have
324 Kerberos-based accounts.
325 dtlogin auth requisite pam_smartcard.so.1
328 dtlogin auth requisite pam_authtok_get.so.1
329 dtlogin auth required pam_dhkeys.so.1
330 dtlogin auth required pam_unix_cred.so.1
331 dtlogin auth binding pam_krb5.so.1
332 dtlogin auth required pam_unix_auth.so.1
333 Typically, you would have another service specified in the pam.conf
337 file that would allow local users, such as database, web server, system
338 administrator accounts, to log in to the host machine. For example, the
339 service name "login" could be used for these users. Note that these
340 users should not belong to any roles.
341 The rest of the module types look similar to that shown in the previous
345 example:
346 other account requisite pam_roles.so.1
349 other account required pam_unix_account.so.1
350 other account required pam_krb5.so.1
351 With binding specified in the following, it is important that non-Ker‐
355 beros users specify the repository in which they reside using the -r
356 option with the passwd(1) command. This configuration is also based on
357 the assumptions that:
358 o Kerberos users maintain only their Kerberos passwords;
361 o changing their Unix password is not necessary, given that
363 they are authenticated only through their Kerberos passwords
364 when logging in.
365 other password required pam_dhkeys.so.1
367 other password requisite pam_authtok_get.so.1
368 other password requisite pam_authtok_check.so.1
369 other password binding pam_krb5.so.1
370 other password required pam_authtok_store.so.1
371 Example 3 Authenticate Through Kerberos Optionally
374 This configuration is helpful when the majority of users are non-Ker‐
377 beros users and would like to authenticate through Kerberos if they
378 happened to exist in the Kerberos database. The effect of this is simi‐
379 lar to users voluntarily executing kinit(1) after they have success‐
380 fully logged in:
381 dtlogin auth requisite pam_smartcard.so.1
384 dtlogin auth requisite pam_authtok_get.so.1
385 dtlogin auth required pam_dhkeys.so.1
386 dtlogin auth required pam_unix_cred.so.1
387 dtlogin auth required pam_unix_auth.so.1
388 dtlogin auth optional pam_krb5.so.1
389 The rest of the configuration is as follows:
393 other account requisite pam_roles.so.1
396 other account required pam_unix_account.so.1
397 other account required pam_krb5.so.1
398 other password required pam_dhkeys.so.1
400 other password requisite pam_authtok_get.so.1
401 other password requisite pam_authtok_check.so.1
402 other password required pam_authtok_store.so.1
403 other password optional pam_krb5.so.1
404 Non-Kerberos users should specify their respective repositories by
408 using the -r option when changing their password with the passwd(1)
409 command.
410
413 See attributes(5) for descriptions of the following attributes:
414 ┌─────────────────────────────┬─────────────────────────────┐
419 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
420 ├─────────────────────────────┼─────────────────────────────┤
421 │Interface Stability │Evolving │
422 └─────────────────────────────┴─────────────────────────────┘
423
425 kdestroy(1), kinit(1), kpasswd(1), passwd(1), ktkt_warnd(1M), lib‐
426 pam(3LIB), pam(3PAM), pam_sm(3PAM), pam_sm_acct_mgmt(3PAM),
427 pam_sm_authenticate(3PAM), pam_sm_chauthtok(3PAM), pam_sm_close_ses‐
428 sion(3PAM), pam_sm_open_session(3PAM), pam_sm_setcred(3PAM), sys‐
429 log(3C), pam.conf(4), attributes(5), kerberos(5), krb5envvar(5)
430
432 The interfaces in libpam(3LIB) are MT-Safe only if each thread within
433 the multi-threaded application uses its own PAM handle.
434 On successful acquisition of initial credentials (ticket-granting
437 ticket), ktkt_warnd(1M) will be notified, to alert the user when the
438 initial credentials are about to expire.
439SunOS 5.11 8 Apr 2008 pam_krb5(5)