whitelist for fighting spam
[openafs-wiki.git] / 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