AFSLore/EnablingAFSLoginonLinuxSystems.mdwn

   1 At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for authenticated access to and from the machine.
   2
   3 Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of settings in the PAM configuration file (for example, how the other entry works, the effect of marking an entry as required, optional, or sufficient, and so on).
   4
   5 The following instructions explain how to alter the entries in the PAM configuration file for each service for which you wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and tested configuration.
   6
   7 The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three attributes.
   8
   9     try_first_pass
  10
  11 This is a standard PAM attribute that can be included on entries after the first one for a service; it directs the module to use the password that was provided to the first module. For the AFS module, it means that AFS authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For further discussion of this attribute and its alternatives, see the operating system's PAM documentation.
  12
  13     ignore_root
  14
  15 This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero).
  16
  17     ignore_uid uid
  18
  19 This option is an extension of the "ignore\_root" switch. The additional parameter is a limit. Users with a uid up to the given parameter are ignored by pam\_afs.so. Thus, a system administrator still has the opportunity to add local user accounts to his system by choosing between "low" and "high" user ids. An example /etc/passwd file for "ignore\_uid 100" may have entries like these:
  20
  21             .
  22             .
  23     afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash
  24     afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash
  25     localuserone:x:101:100::/home/localuserone:/bin/bash
  26     localusertwo:x:102:100::/home/localusertwo:/bin/bash
  27             .
  28             .
  29
  30 AFS accounts should be locked in the file /etc/shadow like this:
  31
  32             .
  33             .
  34     afsuserone:!!:11500:0:99999:7:::
  35     afsusertwo:!!:11500:0:99999:7:::
  36     localuserone:<thelocaluserone'skey>:11500:0:99999:7:::
  37     localusertwo:<thelocalusertwo'skey>:11500:0:99999:7:::
  38             .
  39             .
  40
  41 There is no need to store a local key in this file since the AFS password is sent and verfied at the AFS cell server!
  42
  43     setenv_password_expires
  44
  45 This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD\_EXPIRES to the expiration date of the user's AFS password, which is recorded in the Authentication Database.
  46
  47     set_token
  48
  49 Some applications don't call pam\_setcred() in order to retrieve the appropriate credentials (here the AFS token) for their session. This switch sets the credentials already in pam\_sm\_authenticate() obsoleting a call to pam\_setcred(). Caution: Don't use this switch for applications which do call pam\_setcred()! One example for an application not calling pam\_setcred() are older versions of the samba server. Nevertheless, using applications with working pam session management is recommended as this setup conforms better with the PAM definitions.
  50
  51     refresh_token
  52
  53 This options is identical to "set\_token" except that no new PAG is generated. This is necessary to handle processes like xlock or xscreensaver. It is not enough to give the screen and the keyboard free for the user who reactivated his screen typing in the correct AFS password, but one may also need fresh tokens with full livetime in order to work on, and the new token must be refreshed in the already existing PAG for the processes that have been started. This is achieved using this option.
  54
  55     use_klog
  56
  57 Activating this switch the authentication is done by calling the external program "klog". One program requiring this is for example kdm of KDE 2.x.
  58
  59     dont_fork
  60
  61 Usually, the password verification and the establishment of the token is performed in a sub process. Using this option pam\_afs does not fork and performs all actions in a single process. Only use this options in case you notice serious problems caused by the sub process. This option has been developed in respect to the "mod\_auth\_pam"-project (see also mod\_auth\_pam). The mod\_auth\_pam module enables PAM authentication for the apache http server package.
  62
  63 Session Management
  64
  65     no_unlog
  66
  67 Normally the tokens are deleted (in memory) after the session ends. Using this options the tokens are left untouched. This behaviour has been the default in pam\_afs until openafs-1.1.1!
  68
  69     remainlifetime sec
  70
  71 The tokens are kept active for sec seconds before they are deleted. X display managers i.e. are used to inform the applications started in the X session before the logout and then end themselves. If the token was deleted immediately the applications would have no chance to write back their settings to i.e. the user's AFS home space. This option may help to avoid the problem.
  72
  73 Perform the following steps to enable AFS login.
  74
  75 1. Mount the AFS CD-ROM for Linux on the /cdrom directory, if it is not already. Then change to the directory for PAM modules, which depends on which Linux distribution you are using.
  76
  77 If you are using a Linux distribution from Red Hat Software:
  78
  79        # cd /lib/security
  80
  81 If you are using another Linux distribution:
  82
  83        # cd /usr/lib/security
  84
  85 1. Copy the appropriate AFS authentication library file to the directory to which you changed in the previous step. Create a symbolic link whose name does not mention the version. Omitting the version eliminates the need to edit the PAM configuration file if you later update the library file.
  86
  87 If you use the AFS Authentication Server (kaserver process):
  88
  89        # cp /cdrom/i386_linux22/lib/pam_afs.so.1  .
  90
  91        # ln -s pam_afs.so.1 pam_afs.so
  92
  93 If you use a Kerberos implementation of AFS authentication:
  94
  95        # cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1   .
  96
  97        # ln -s pam_afs.krb.so.1 pam_afs.so
  98
  99 1. For each service with which you want to use AFS authentication, insert an entry for the AFS PAM module into the auth section of the service's PAM configuration file. (Linux uses a separate configuration file for each service, unlike some other operating systems which list all services in a single file.) Mark the entry as sufficient in the second field.
 100
 101 Place the AFS entry below any entries that impose conditions under which you want the service to fail for a user who does not meet the entry's requirements. Mark these entries required. Place the AFS entry above any entries that need to execute only if AFS authentication fails.
 102
 103 Insert the following AFS entry if using the Red Hat distribution:
 104
 105        auth  sufficient  /lib/security/pam_afs.so   try_first_pass  ignore_root
 106
 107 Insert the following AFS entry if using another distribution:
 108
 109        auth  sufficient  /usr/lib/security/pam_afs.so  try_first_pass  ignore_root
 110
 111 Check the PAM config files also for "session" entries. If there are lines beginning with "session" then please insert this line too:
 112
 113        session  optional  /lib/security/pam_afs.so
 114
 115 or
 116
 117        session  optional  /usr/lib/security/pam_afs.so
 118
 119 This guaranties that the user's tokens are deleted from memory after his session ends so that no other user coincidently gets those tokens without authorization! The following examples illustrate the recommended configuration of the configuration file for several services:
 120
 121 Authentication Management (/etc/pam.d/login)
 122
 123        #%PAM-1.0
 124        auth      required   /lib/security/pam_securetty.so
 125        auth      required   /lib/security/pam_nologin.so
 126        auth      sufficient /lib/security/pam_afs.so try_first_pass ignore_root
 127        #                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 128        #This enables AFS authentication for every user but root
 129        auth      required   /lib/security/pam_pwdb.so shadow nullok
 130        account   required   /lib/security/pam_pwdb.so
 131        password  required   /lib/security/pam_cracklib.so
 132        password  required   /lib/security/pam_pwdb.so shadow nullok use_authtok
 133        session   optional   /lib/security/pam_afs.so
 134        #Make sure tokens are deleted after the user logs out
 135        session   required   /lib/security/pam_pwdb.so
 136
 137 (/etc/pam.d/samba)
 138
 139        auth       required     /lib/security/pam_afs.so ignore_uid 100 set_token
 140        #                                                ^^^^^^^^^^^^^^^^^^^^^^^^
 141        #Here, users with uid>100 are considered to belong to the AFS and users
 142        #with uid<=100 are ignored by pam_afs. The token is retrieved already in
 143        #pam_sm_authenticate() (this is an example pam config for a samba version
 144        #that does not call pam_setcred(), it also does no sense to include session
 145        #entries here since they would be ignored by this version of samba ).
 146        account    required     /lib/security/pam_pwdb.so
 147
 148 (/etc/pam.d/xscreensaver)
 149
 150        auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 refresh_token
 151        #                                                               ^^^^^^^^^^^^^
 152        #Avoid generating a new PAG for the new tokens, use the already existing PAG and
 153        #establish a fresh token in it.
 154        auth       required     /lib/security/pam_pwdb.so try_first_pass
 155
 156 (/etc/pam.d/httpd)
 157
 158        auth       required   /lib/security/pam_afs.so ignore_uid 100 dont_fork
 159        #                                                             ^^^^^^^^^
 160        #Don't fork for the verification of the password.
 161
 162 Session Management (/etc/pam.d/su)
 163
 164        auth       sufficient   /lib/security/pam_afs.so ignore_uid 100
 165        auth       required     /lib/security/pam_pwdb.so try_first_pass
 166        account    required     /lib/security/pam_pwdb.so
 167        password   required     /lib/security/pam_cracklib.so
 168        password   required     /lib/security/pam_pwdb.so use_authtok
 169        session    required     /lib/security/pam_pwdb.so
 170        session    optional     /lib/security/pam_afs.so no_unlog
 171        #                                                ^^^^^^^^
 172        #Don't delete the token in this case, since the user may still
 173        #need it (for example if somebody logs in and changes to root
 174        #afterwards he may still want to access his home space in AFS).
 175        session    required     /lib/security/pam_login_access.so
 176        session    optional     /lib/security/pam_xauth.so
 177
 178 (/etc/pam.d/xdm)
 179
 180        auth       required     /lib/security/pam_nologin.so
 181        auth       required     /lib/security/pam_login_access.so
 182        auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 use_klog
 183        auth       required     /lib/security/pam_pwdb.so try_first_pass
 184        account    required     /lib/security/pam_pwdb.so
 185        password   required     /lib/security/pam_cracklib.so
 186        password   required     /lib/security/pam_pwdb.so shadow nullok use_authtok
 187        session    optional     /lib/security/pam_afs.so remainlifetime 10
 188        #                                                ^^^^^^^^^^^^^^^^^
 189        #Wait 10 seconds before deleting the AFS tokens in order to give
 190        #the programs of the X session some time to save their settings
 191        #to AFS.
 192        session    required     /lib/security/pam_pwdb.so