[cgiwrap-users] Kerberos 5 / AFS authentication patch
Brought to you by:
nneul
Menu
▾
▴
[cgiwrap-users] Kerberos 5 / AFS authentication patch
|
From: Mark M. <mar...@um...> - 2003-07-31 22:35:35
|
I've created a patch for CGIwrap 3.8 that enables CGIwrap to get
Kerberos 5 tickets and AFS tokens on a per-user basis on behalf of
the CGIs that it runs. Documentation on what this patch does and
how to use it is at the end of this message. The patch itself and
more information are available from
http://unix.lsa.umich.edu/cgiwrap/
I'm looking for advanced admins to be early testers and provide
feedback. Right now, the patch works for me in my environment but
that's about all I'm willing to guarantee about it. I don't know
of any problems with the patch at the current time, but I expect
that a number of problems will be discovered as people try to use
this patch in their own environments, and it may take a while to
find and fix them all.
If you have any questions or feedback, please let me know.
Mark Montague
LS&A Information Technology
The University of Michigan
mar...@um...
------------------------------------------------------------------------------
CGIwrap - Usage with Kerberos 5
_________________________________________________________________
Ideally, a CGI script would acquire and manage any credentials it
needs in order to run. But there are several scenarios in which it is
beneficial to have CGIwrap manage Kerberos credentials on behalf of
the CGI scripts which run under it:
* The user who installed the CGI may not be the CGI's author and may
prefer (or lack the skills) to modify it, and the CGI's author may
not have anticipated the need for the CGI to run in a Kerberos
environment. If the CGI is a binary (particularly a commercial
application) it may not be possible to modify it to add Kerberos
support.
* The user who wrote and installed the CGI may not be aware of the
larger web server environment in which their CGI runs and may want
it to "just work" with other infrastructure services. This allows
the author to focus on the purpose of the CGI script and avoid
having to deal with what they consider to be unrelated details. An
example of users in this category are University faculty.
CGIwrap can therefore be configured to obtain and manage Kerberos 5
credentials on behalf of the users who own the CGIs. Credentials are
obtained and managed separately for each user. Credentials are saved
between CGI invocations and, when necessary, automatically renewed.
This means that once credentials have been obtained for a user, other
scripts owned by that user can re-use the without having to contact
the Kerberos server each time.
IMPORTANT NOTE: CGIwrap has been tested with MIT Kerberos version
1.2.5. CGIwrap will probably not work with non-MIT Kerberos
distributions.
Configuring CGIwrap for Kerberos 5
To enable Kerberos 5 support in CGIwrap, give the --with-krb5 option
to the configure script when building CGIwrap. configure will try to
find the krb5-config script that comes with MIT Kerberos versions
1.2.3 and later, and it will use this script to determine the
appropriate compilation and linking flags for Kerberos. You can
override the location of this script by using the --with-krb5-config
option.
In order to obtain Kerberos credentials for users, CGIwrap needs a
keytab for each user. (A keytab is a file containing keys -- binary
passwords -- for a user). By default, keytabs for all users are stored
in the directory /usr/adm/cgiwrap-keytabs although this can be
overridden using the --with-krb5-keytab-dir option. If you want to
have the same user get different credentials depending upon which
virtual host the CGI is being run under, use the
--with-vhost-krb5-keytab-dir option -- in this case, CGIwrap will
first read any global keytab for the user from krb5-keytab-dir and
then look in vhost-krb5-keytab-dir for a subdirectory whose name is
the all-lowercase value of the HTTP_HOST environment variable (or, if
the --with-vhost-override option was given, it will look in the
subdirectory whose name is the all-lowercase value of the
CGIWRAP_AUTH_VHOST environment variable). Both global and
vhost-specific keytabs will be read, but keys in vhost-specific
keytabs will be tried first before keys from the global keytab.
The keytab directories need to be created manually. They must be owned
by root and must not be writable by any user other than root. Since
Kerberos keys are functionally equivalent to passwords, it is strongly
recommended that the keytab directories also be restricted so that
they can only be read by root. (Note that there will only be a single
keytab directory unless you specified --with-vhost-krb5-keytab-dir).
If you have configured CGIwrap to use its chroot facility, the keytab
directories must be outside the chroot area.
CGIwrap will cache any Kerberos credentials (ticket) that it obtains
so that it can re-use them on subsequent invocations, thus avoiding
the need to contact the Kerberos server each time a CGI is executed.
By default, these credentials caches are stored in the directory /tmp
although this can be changed using the --with-krb5-ccache-dir option.
For increased security, it is highly recommended that you specify
another directory (such as /ticket) that will only be used for storing
Kerberos credentials caches (the only reason /tmp is the default is
because this is where most users and applications expect to find
Kerberos credentials caches). To enable each virtual host to have its
own credentials cache directory, use the --with-vhost-krb5-ccache-dir
option; credentials caches will then be stored in the subdirectory
whose name is the all-lowercase value of the HTTP_HOST environment
variable (or, if the --with-vhost-override option was given, it will
look in the subdirectory whose name is the all-lowercase value of the
CGIWRAP_AUTH_VHOST environment variable). If
--with-vhost-krb5-ccache-dir is given, then the "global" directory
specified with --with-krb5-ccache-dir will never be used.
The credentials cache directories must be manually created unless they
already exist on the web server. They must be owned by root, and
writable by all users for whom CGIwrap will be obtaining Kerberos
credentials. The Unix "sticky bit" must be set on the credentials
cache directories in order to prevent the credentials cache files from
being tampered with by other users. Unix directory permissions of 1733
are recommended. For further security, consider making the credentials
cache directories reside on a memory based filesystem. If you have
configured CGIwrap to use its chroot facility, the credentials cache
directories must be inside the chroot area; this means that each user
will effectively have their own credentials cache directory.
When CGIwrap runs for a particular user, it examines all cached
credentials and will renew any which have already expired or are about
to expire. By default, any credential that has expired or will expire
within the next 1800 seconds (1/2 hour) will be renewed. This can be
changed using the --with-ticket-renewal-window option.
When CGIwrap obtains credentials, it will by default request that they
have a lifetime of 2592000 seconds (1 month). This, in effect, causes
the ticket to be issued with the maximum lifetime permitted by the
principal in the Kerberos database for which the ticket was requested
(see below) or the maximum lifetime permitted by the Kerberos realm
itself, whichever is less. This behavior can be changed using the
-with-ticket-max-lifetime option.
Example:
At the University of Michigan, CGIwrap is built with the following
options:
--with-krb5
--with-krb5-keytab-dir="/opt/www/etc/cgiwrap-keytabs"
--with-krb5-ccache-dir="/ticket"
After building CGIwrap, the system administrator manually runs the
following commands:
# mkdir /opt/www/etc/cgiwrap-keytabs
# chown root:other /opt/www/etc/cgiwrap-keytabs
# chmod 700 /opt/www/etc/cgiwrap-keytabs
# mkdir /ticket
# chown root:other /ticket
# chmod 1733 /ticket
Per-user Kerberos 5 configuration
If no keytab exists for a user, CGIwrap will not try to obtain any
Kerberos credentials, although it will make available any credentials
available to the CGI which have been manually obtained and placed in
the user's credentials cache. Usually, though, you will need to create
a keytab for each user who will be running CGIs that need Kerberos
credentials. If you are not a Kerberos administrator, you can have
your realm's Kerberos administrator create the keytabs for you and you
can then simply copy them to your web server machine.
You can have multiple keys in a user's keytab. When CGIwrap runs a CGI
owned by the user, it will attempt to obtain a Kerberos ticket for
each entry listed in the keytab. Not all keys in the keytab have to be
for the same principal.
The act of adding an entry to a keytab changes the password for the
principal (user) involved. Therefore, if you want to configure CGIwrap
to obtain Kerberos credentials for CGIs owned by a user with the user
name "joe", you would not create the keytab for "joe" -- if you did,
the user would no longer be able to authenticate using the password
they set. Instead, create a new principal: "joe/www", "joe/cgiwrap",
"joe/example.web.server.name" or even "j1234" -- CGIwrap makes no
assumptions about the names.
Once the keytab is created, copy it to the correct keytab directory or
directories. The keytab must be owned by the user or by root, and must
be readable only by the user and/or root. The name of the keytab file
must be krb5.keytab.USERNAME (for example, "krb5.keytab.joe").
Depending on what the CGIs that use the tickets acquired by CGIwrap
do, you may need to create resources or assign rights to each
principal listed in the keytab. For example, assume the user "joe" has
a CGI that searches a shared Cyrus IMAP mailbox for any email messages
whose subject line begins with the string "URGENT:" that have not been
responded to and displays these messages on a web page. The keytab for
user "joe" contains an entry for "joe/www@EXAMPLE.KERBEROS.REALM". You
would need to use the Cyrus IMAP cyradm utility to grant the user
"joe/www" read access to the shared mailbox (even though "joe" may
already have access).
No action needs to be taken with regards to a credentials cache for
the user; it will be automatically created by CGIwrap.
Example:
At the University of Michigan, the following commands are used to do
the per-user Kerberos 5 set up for CGIwrap users. This example is for
user "joe" in the Kerberos realm LSA.UMICH.EDU:
# kadmin -p admmark/admin
Authenticating as principal admmark/admin with password.
Enter password:
kadmin: addprinc -randkey joe/www
WARNING: no policy specified for joe/www@LSA.UMICH.EDU;
defaulting to no policy
Principal "joe/www@LSA.UMICH.EDU" created.
kadmin: ktadd -k /opt/www/etc/cgiwrap-keytabs/krb5.keytab.joe joe/www
Entry for principal joe/www with kvno 3, encryption type DES cbc mode with
CRC-32 added to keytab WRFILE:/opt/www/etc/cgiwrap-keytabs/krb5.keytab.joe.
kadmin: quit
The following commands can be used to verify that everything is okay
and that CGIwrap will be able to use the keytab successfully. ("5678"
below is is joe's numerical user id from the /etc/passwd file, LDAP,
or NIS+).
# ls -l /opt/www/etc/cgiwrap-keytabs/krb5.keytab.joe
-rw------- 1 root other 54 Jul 31 09:10 /opt/www/etc/cgiwrap-
keytabs/krb5.keytab.joe
# klist -k /opt/www/etc/cgiwrap-keytabs/krb5.keytab.joe
Keytab name: FILE:/opt/www/etc/cgiwrap-keytabs/krb5.keytab.joe
KVNO Principal
---- --------------------------------------------------------------------
3 joe/www@LSA.UMICH.EDU
# kinit -5 -k -t /opt/www/etc/cgiwrap-keytabs/krb5.keytab.joe -c /ticket/kr
b5cc_test_5678 joe/www
# klist /ticket/krb5cc_test_5678
Ticket cache: FILE:/ticket/krb5cc_test_5678
Default principal: joe/www@LSA.UMICH.EDU
Valid starting Expires Service principal
07/31/03 09:22:17 07/31/03 19:22:20 krbtgt/LSA.UMICH.EDU@LSA.UMICH.EDU
# rm /ticket/krb5cc_test_5678
Now when one of joe's CGIs is run, CGIwrap will obtain a Kerberos 5
ticket granting ticket for it for joe/www in the LSA.UMICH.EDU realm.
------------------------------------------------------------------------------
CGIwrap - Usage with AFS
_________________________________________________________________
CGIwrap will work out of the box with AFS, with at least the following
directory permissions:
Dir User/Group Permissions
~ system:anyuser l
~/public_html system:anyuser l
~/public_html system:anyuser rl
If you are running httpd authenticated as an AFS userid, you can
replace system:anyuser above with that userid.
Process authentication group support
If you are using CGIwrap with AFS I'd suggest making sure to enable
the AFS support in the configure script (--with-afs). This
automatically creates a PAG for any script that is launched, that way
if the script klogs, it won't affect the server or other scripts. When
using cgiwrap with AFS based accounts, you need to keep in mind that
scripts are run un-authenticated. This means that any files that are
accessed will be accessed as system:anyuser. In general, this means
that the script will not have write access to your directory. See
below for information on how to have CGIwrap acquire AFS tokens on
behalf of the user who owns the script.
AFS authentication support
The reasons to have CGIwrap authenticate to AFS for scripts rather
than requiring scripts to authenticate to AFS themselves are the same
as the reasons for having CGIwrap authenticate to Kerberos 5. See Use
of CGIwrap with Kerberos 5.
IMPORTANT NOTE: Currently, in order to have CGIwrap authenticate to
AFS, you need to be running your AFS cell from a Kerberos 5 realm. The
Kerberos 5 KDC machine(s) must also be running krb524d. It is not
currently possible for CGIwrap to authenticate to AFS if you are using
Kerberos 4 and/or the AFS kaserver, and since OpenAFS is moving
towards native Kerberos 5 support, it is unlikely that this
functionality will be added to CGIwrap. If you are running AFS but not
Kerberos 5, please take a look at the AFS Kerberos 5 Migration Kit.
ANOTHER IMPORTANT NOTE: Currently, AFS authentication support in CGI
wrap requires you to use a relatively recent version of the OpenAFS
client libraries. This code has been tested with OpenAFS 1.2.9.
Configuring CGIwrap for AFS authentication
Before configuring CGIwrap for use with AFS, you must first configure
CGIwrap for use with Kerberos 5. See Use of CGIwrap with Kerberos 5
for instructions on how to do this.
Build CGIwrap with the "--with-afs --with-afs-auth" options.
CGIwrap will attempt to get Kerberos 5 ticket granting tickets for
each key in the user's keytab file. It will then attempt to use each
ticket granting ticket to acquire an AFS service ticket for the cell
with the same realm name contained the ticket granting ticket instance
(and it will later convert these Kerberos 5 AFS service tickets into
AFS tokens). For simple AFS cell and Kerberos realm configurations,
this strategy is adequate. For more complex situations involving
multiple AFS cells using a single Kerberos realm for authentication,
or situations where there are multiple Kerberos realms with
cross-realm trust relationships, CGIwrap needs more information on
what AFS cells to authenticate to. It uses the ~/.cgiwrap-afs-auth
file for this purpose. This file contains a list of AFS users, one per
line, for whom CGIwrap should attempt to acquire tokens. White space
is ignored and comments are indicated with a pound sign ('#'). For
example,
joe.www@some.example.cell # Get a token for joe.www in this cell...
joe.www@another.example.cell # ...as well as for this one.
The --with-afs-auth-file option can be used to specify another
location for this file, relative to the user's home directory.
--with-afs-auth-file="Public/.cell_info" would cause CGIwrap to look
in the file ~/Public/.cell_info for each user to determine what AFS
cells to authenticate to.
Per-user configuration for AFS authentication
In order to set up AFS authentication for a user, you must first set
up Kerberos 5 authentication for the user under CGIwrap. See Use of
CGIwrap with Kerberos 5 for instructions on how to do this.
Use the "pts createuser" command to ensure that the user exists in the
AFS PTS database. Replace the slash that separates the user and
instance name in the Kerberos 5 principal with a period. For example,
if the Kerberos 5 keytab contains an key for "joe/www" then you would
run "pts createuser joe.www".
Create an AFS authentication file, if necessary (see above). This file
is only necessary when CGIwrap cannot figure out the what tokens to
get on its own.
Set AFS ACLs. The ACLs should be the same as in the table above,
except that the cgi-bin directory needs to be readable by the web
server both before and after it obtains the user's AFS tokens. In
addition, specific rights can be granted to the AFS user for whom
CGIwrap obtained tokens in order to control what the CGI scripts
can/cannot do. For example, for a guest book CGI, the guest book might
store its database in the directory ~/guest-db. This directory could
then be set up with the following ACLs:
joe rlidwka
joe.www rli
system:anyuser none
...thus giving the user full access to the directory, allowing the CGI
to read files from the directory and add new files but not change or
delete any existing file, and keeping the directory contents private
from everyone else.
------------------------------------------------------------------------------
|