1pam_krb5(8)              System Administrator's Manual             pam_krb5(8)
2
3
4

NAME

6       pam_krb5 - Kerberos 5 authentication
7
8

SYNOPSIS

10       auth required //usr/$LIB/security/pam_krb5.so
11       session optional //usr/$LIB/security/pam_krb5.so
12       account sufficient //usr/$LIB/security/pam_krb5.so
13       password sufficient //usr/$LIB/security/pam_krb5.so
14
15

DESCRIPTION

17       The  pam_krb5.so module is designed to allow smooth integration of Ker‐
18       beros 5 password-checking for applications which use PAM.   It  creates
19       session-specific credential caches.  If the system is an AFS client, it
20       will also attempt to obtain tokens for the local cell, the  cell  which
21       contains  the  user's  home  directory,  and  any explicitly-configured
22       cells.
23
24       When a user logs in, the module's authentication  function  performs  a
25       simple password check and, if possible, obtains Kerberos 5 credentials,
26       caching them for later use.  When the application requests  initializa‐
27       tion  of  credentials  (or opens a session), the usual ticket files are
28       created.  When the application subsequently requests deletion  of  cre‐
29       dentials  or  closing  of  the  session,  the module deletes the ticket
30       files.  When the application requests account management, if the module
31       did  not  participate in authenticating the user, it will signal libpam
32       to ignore the module.  If the module did participate in  authenticating
33       the  user,  it  will  check for an expired user password and verify the
34       user's authorization using the .k5login file of the user being  authen‐
35       ticated, which is expected to be accessible to the module.
36
37

ARGUMENTS

39       debug  turns on debugging via syslog(3).  Debugging messages are logged
40              with priority LOG_DEBUG.
41
42
43       debug_sensitive
44              turns on  debugging  of  sensitive  information  via  syslog(3).
45              Debug messages are logged with priority LOG_DEBUG.
46
47
48       afs_cells=cell.example.com[,...]
49              tells pam_krb5.so to obtain tokens for the named cells, in addi‐
50              tion to the local cell, for the user.  The module will guess the
51              principal name of the AFS service for the named cells, or it can
52              be specified by giving cell in the form cellname=principalname.
53
54
55       always_allow_localname
56              tells pam_krb5.so, when performing an authorization check  using
57              the target user's .k5login file, to always allow access when the
58              principal name being authenticated maps to the local user's name
59              (as  configured  using the auth_to_local_names and auth_to_local
60              settings in krb5.conf(5), if your implementation provides  those
61              settings).   Otherwise,  if the file exists and can be read, but
62              the principal is not  explicitly  listed,  access  is  typically
63              denied.  This setting is disabled by default.
64
65
66       armor = true|false|service [...]
67              attempt  to  use armoring when communicating with the KDC.  This
68              option is currently mainly  only  useful  for  testing,  as  the
69              keytab  method should not be expected to work when the module is
70              called from an  unprivileged  process,  and  the  pkinit  method
71              requires  that the KDC is properly configured to offer anonymous
72              PKINIT, and that the client is also properly configured to trust
73              the KDC's CA.  The default is false.
74
75
76       armor_strategy = keytab,pkinit
77              controls  how  the module will attempt to obtain tickets for use
78              as armor.  The value should be a comma-separated list  of  meth‐
79              ods.   Supported methods include ketyab and pkinit.  The default
80              is keytab,pkinit.
81
82
83       banner=Kerberos 5
84              tells pam_krb5.so how to identify itself when users  attempt  to
85              change their passwords.  The default setting is "Kerberos 5".
86
87
88       ccache_dir=/tmp
89              tells  pam_krb5.so which directory to use for storing credential
90              caches.  The default setting is /tmp.
91
92
93       ccname_template=DIR:/run/user/%U/krb5cc_XXXXXX
94              specifies the location in which to place the user's session-spe‐
95              cific  credential  cache.   This value is treated as a template,
96              and these sequences are substituted:
97                %u login name
98                %U login UID
99                %p principal name
100                %r principal's realm name
101                %h home directory
102                %d the default ccache directory (as set with ccache_dir)
103                %P the current process ID
104                %% literal '%'
105              If the resulting template does not end with "XXXXXX",  a  suffix
106              will  be  added to the configured value.  If not set, the module
107              attempts to read the default used by libkrb5 from  krb5.conf(5),
108              and     if    one    is    not    found,    the    default    is
109              DIR:/run/user/%U/krb5cc_XXXXXX".
110
111
112       chpw_prompt
113              tells pam_krb5.so to allow expired passwords to be changed  dur‐
114              ing  authentication  attempts.   While  this  is the traditional
115              behavior exhibited by  "kinit",  it  is  inconsistent  with  the
116              behavior  expected  by  PAM,  which  expects  authentication  to
117              (appear to) succeed, only to have password expiration be flagged
118              by  a  subsequent call to the account management function.  Some
119              applications which don't handle  password  expiration  correctly
120              will fail unconditionally if the user's password is expired, and
121              this flag can be used to attempt to  work  around  this  bug  in
122              those applications.  The default is false.
123
124
125       cred_session
126              specifies  that  pam_krb5  should  create and destroy credential
127              caches, as it does when the calling application opens and closes
128              a  PAM  session,  when  the  calling application establishes and
129              deletes PAM credentials.  This is done to compensate for  appli‐
130              cations  which  expect  to  create  a credential cache but which
131              don't use PAM session management.   It  is  usually  a  harmless
132              redundancy  in  applications  which  don't  require  it, so this
133              option is enabled by default except for these services: "sshd".
134
135
136       external
137
138       external=sshd
139              tells pam_krb5.so to use Kerberos credentials  provided  by  the
140              calling  application  during  session setup.  This is most often
141              useful for obtaining AFS tokens.
142
143
144       ignore_afs=true|false|service [...]
145              tells pam_krb5.so to completely ignore the presence of AFS, pre‐
146              venting any attempts to obtain new tokens on behalf of the call‐
147              ing application.
148
149
150       ignore_k5login
151              specifies that pam_krb5 should skip checking the user's .k5login
152              file  to  verify  that  the  principal  name of the client being
153              authenticated is authorized to access the user account.   (Actu‐
154              ally,  the  check is performed by a function offered by the Ker‐
155              beros library, which controls which files it will consult.)  The
156              default is to perform the check.
157
158
159       ignore_unknown_principals
160
161       ignore_unknown_spn
162
163       ignore_unknown_upn
164              specifies  that  not pam_krb5 should return a PAM_IGNORE code to
165              libpam instead of PAM_USER_UNKNOWN for users for whom the deter‐
166              mined principal name is expired or does not exist.
167
168
169       keytab=FILE:/etc/krb5.keytab
170              tells  pam_krb5.so the location of a keytab to use when validat‐
171              ing credentials obtained from KDCs.
172
173
174       minimum_uid=0
175              tells pam_krb5.so to ignore  authentication  attempts  by  users
176              with UIDs below the specified number.
177
178
179       multiple_ccaches
180              specifies  that  pam_krb5  should  maintain  multiple credential
181              caches for this service, because it both  sets  credentials  and
182              opens  a  PAM session, but it sets the KRB5CCNAME variable after
183              doing only one of the two.  This option is usually not necessary
184              for most services.
185
186
187       no_initial_prompt
188              tells  pam_krb5.so  to  not ask for a password before attempting
189              authentication, and to instead allow  the  Kerberos  library  to
190              trigger  a  request  for  a  password only in cases where one is
191              needed.
192
193
194       no_subsequent_prompt
195              tells pam_krb5.so to only provide the  previously-entered  pass‐
196              word  in  response  to any request for a password which the Ker‐
197              beros library might make.  If the calling application  does  not
198              properly  support PAM conversations (possibly due to limitations
199              of a network protocol which it is serving), this may be need  to
200              be  used  to  prevent  the application from supplying the user's
201              current password in a password-changing situations  when  a  new
202              password is called for.
203
204
205       no_user_check
206              tells  pam_krb5.so  to  not  check if a user exists on the local
207              system, to skip authorization checks using the  user's  .k5login
208              file,  and to create ccaches owned by the current process's UID.
209              This is useful for  situations  where  a  non-privileged  server
210              process  needs  to  use  Kerberized services on behalf of remote
211              users who may not have local access.  Note that  such  a  server
212              should  have an encrypted connection with its client in order to
213              avoid allowing the user's password to be eavesdropped.
214
215
216       no_validate
217
218       no_validate=vlock
219              tells pam_krb5.so to not attempt to use the local keytab to ver‐
220              ify  that the TGT obtained from the realm's servers has not been
221              spoofed.   The  libdefaults  verify_ap_req_nofail  setting   can
222              affect  whether  or  not  errors  reading  the  keytab which are
223              encountered during validation will be suppressed.
224
225
226       null_afs
227              tells pam_krb5.so, when it attempts to set tokens, to try to get
228              credentials  for  services  with  names which resemble afs@REALM
229              before attempting to get credentials  for  services  with  names
230              resembling  afs/cell@REALM.   The  default is to assume that the
231              cell's name is the instance in the AFS service's Kerberos  prin‐
232              cipal name.
233
234
235       preauth_options=[]
236              controls  the preauthentication options which pam_krb5 passes to
237              libkrb5, if the system-defaults need to be overridden.  The list
238              is treated as a template, and these sequences are substituted:
239
240                %u login name
241                %U login UID
242                %p principal name
243                %r principal's realm name
244                %h home directory
245                %d the default ccache directory
246                %P the current process ID
247                %% literal '%'
248
249              A  list  of  recognized  values should be listed in the kinit(1)
250              manual page as parameters for its -X option.
251
252
253       pwhelp=filename
254              specifies the name of a text file whose contents  will  be  dis‐
255              played  to clients who attempt to change their passwords.  There
256              is no default.
257
258
259       realm=realm
260              overrides  the  default  realm  set  in  /etc/krb5.conf,   which
261              pam_krb5.so will attempt to authenticate users to.
262
263
264       tokens
265
266       tokens=imap
267              signals  that pam_krb5.so should create a new AFS PAG and obtain
268              AFS tokens during authentication in addition to  session  setup.
269              This  is  primarily  useful in server applications which need to
270              access a user's files but which do not open PAM sessions  before
271              doing so.  A properly-written server will not need this flag set
272              in order to function correctly.
273
274
275       trace  turns on libkrb5's library tracing.  Trace messages  are  logged
276              to syslog(3) with priority LOG_DEBUG.
277
278
279       try_first_pass
280              tells  pam_krb5.so  to  check the previously-entered password as
281              with use_first_pass, but to prompt the user for another  one  if
282              the  previously-entered  one  fails. This is the default mode of
283              operation.
284
285
286       use_first_pass
287              tells pam_krb5.so to get the user's entered password as  it  was
288              stored by a module listed earlier in the stack, usually pam_unix
289              or pam_pwdb, instead of prompting the user for it.
290
291
292       use_authtok
293              tells pam_krb5.so to never prompt for new passwords when  chang‐
294              ing  passwords.  This is useful if you are using pam_cracklib or
295              pam_passwdqc to try to enforce use of  less-easy-to-guess  pass‐
296              words.
297
298
299       use_shmem
300
301       use_shmem=sshd
302              tells  pam_krb5.so  to  pass credentials from the authentication
303              service function to  the  session  management  service  function
304              using shared memory, or to do so for specific services.
305
306
307       validate_user_user
308
309       validate_user_user=gnome-screensaver
310              specifies  that, when attempting validation of the TGT, the mod‐
311              ule should attempt user-to-user authentication  using  a  previ‐
312              ously-obtainted TGT in the default ccache if validation can't be
313              performed using a keytab.
314
315

FILES

317       /etc/krb5.conf
318
319

SEE ALSO

321       pam_krb5(5) krb5.conf(5)
322
323

BUGS

325       Probably, but let's hope not.  If you find any, please file them in the
326       bug database at http://bugzilla.redhat.com/ against the "pam_krb5" com‐
327       ponent.
328
329

AUTHOR

331       Nalin Dahyabhai <nalin@redhat.com>
332
333
334
335Red Hat Linux                     2013/09/21                       pam_krb5(8)
Impressum