Configuring CUWebAuth for Apache

• Being able to authenticate users in the Cornell environment
• Being able to restrict access to web pages based on Cornell NetID

  We’ll look at these configuration issues individually.

Setting up CUWebAuth to Authenticate Users

There are three ways to authenticate users with CUWebAuth:  

• Using CUWebLogin
• Using SideCar (deprecated)
• Using Proxy / Inline Authentication

CUWebLogin relies on a central web server to authenticate the user.    When a restricted page is requested CUWebAuth redirects the user to the CUWebLogin server to get credentials.   The original URL requested on your server by the user is sent along as a parameter so that the CUWebLogin server can redirect the user back to your application after logging in.  

SideCar is a small application that runs on an end user’s machine listening for authentication requests from servers such as those running CUWebAuth.   One limitation of this scenario is that the server needs to be able to initiate a TCP/IP connection to the end user’s machine.    As more and more end users set their machines up behind firewalls and/or Network Address Translators (NATs) OR are running personal firewalls that block access to incoming connections, there have been more instances of users who cannot use SideCar.  SideCar will not be available in future releases of CUWebAuth.

Proxy Authentication is a method by which you can assert that you trust another machine to tell you who a user is.    This other machine will authenticate to your server so that you can verify that you are speaking with a trusted entity.   You would then allow that machine to simply tell you who the user is.   A variation of this method allows end users to authenticate directly to this mechanism thus providing yet another way to directly authenticate to your server.   We have some experimental authentication mechanisms implemented which rely on the Proxy Authentication infrastructure to do direct authentication.

There are an increasing number of ways to authenticate end users.    The pros and cons of all methods will be discussed later.   In general, the more types of authentication you support, the greater the audience that will be able to use your application.

All methods of authentication require some common configuration options to be set, and there will be some configuration options which pertain only to individual authentication methods.

 
Obtaining a Kerberos Identity (SRVTAB)

  Before your web server will be allowed (through CUWebAuth) to authenticate end users, you must obtain an identity for your server.    Only authorized identities are allowed to process Kerberos credentials from end users (to determine their NetID).    These identities are just like an end user’s NetID, but they follow a different naming convention.    The name of this identity along with an arbitrary password assigned when the identity is created are stored in a file called a srvtab (pronounced “serve-tab”).    With a srvtab a server process can authenticate itself to any other kerberized service, and it can also accept authentication credentials submitted by end users.   The name of the identity associated with any given srvtab generally takes the following form:

web-agent.hostname

The first string generally describes the type of authentication you will be performing.    Since CUWebAuth is used to restrict web based access to certain resources, we generally start these principals with the word “web”.   The second string must be “-agent” in order for SideCar to honor the request your instance of CUWebAuth will make for credentials from the end users.   Finally, the last string is usually the hostname (without domain information) .   This is not required, but it is a convention generally followed.

To use CUWebAuth you must obtain a Kerberos identity for your server. This may be done by going to http://aads.cit.cornell.edu/servicerequest and following the sidebar link to “Request srvtab/keytab”.    There will be instructions on what you need to do to request a srvtab.  

CUWebAuth will need to know where the srvtab file containing this identity is located on your machine.    This is specified with a configuration directive in the httpd.conf file.   .   It should be noted here that a srvtab really is a cached id and password for your server.    As such, the access permissions on the file should be very strict.   In general it should be readable only by the uid which owns the process which needs to utilize it (in this case, apache).  

 

 

Once you have a srvtab ready to go you are ready to start editing the httpd.conf file.

Editing the httpd.conf File

In order to activate CUWebAuth, you need to modify your Apache configuration file (httpd.conf). You can find a sample configuration for using CUWebAuth here.   A basic Apache configuration looks something like this:

CUWAkerberosPrincipal web-agent.yourserver
CUWAsrvtabPath        /etc/yourservtabfile
CUWAcuwlServerSRL     "ipHost=cuweblogin.cit.cornell.edu ipPort=1010 a.netid=erpcd.webster a.protocol=k4"
CUWAcuwlServerSRL     "ipHost= cuweblogin2.cit.cornell.edu ipPort=1010 a.netid=erpcd.webster2 a.protocol=k4"
CUWApermitServerSRL   "ipHost=permit1.cit.cornell.edu ipPort=756 a.netid=permitd.permit1 a.protocol=k4"
CUWAcusspTimeout 5        normal

<Directory /test> 
AuthName         CORNELL 
AuthType         all 
require          valid-user 
</Directory>

For now, we will concern ourselves with the directives at the top of the file.

The first directive ( CUWAkerberosPrincipal ) tells CUWebAuth the name of the server’s Kerberos identity.   The @CIT.CORNELL.EDU suffix is the Kerberos realm in which this identity is defined.    It’s important to include this with your identity so that end users who may work in more than one Kerberos realm (a relatively small number of people) will be able to obtain an appropriate credential when using your web site.  Modify mandarin-agent.test to be whatever ServiceID you will be using.

The second directive ( CUWAsrvtabPath ) tells CUWebAuth where your srvtab file is.   This is necessary for decoding tickets and for proving the server’s identity to CUWebLogin.    This file is issued to you when your server identity is set up (http://aads.cit.cornell.edu/servicerequest).

The next two directives ( CUWAcuwlServerSRL ) tells CUWebAuth where to find a valid CUWebLogin server.    You should never need to change these strings unless CIT changes the location of the CUWebLogin server.    The first of these two directives is the primary CUWebLogin server.    In the event that server is unreachable, CUWebAuth will try the host specified in the second instance of the directive.  

The fourth directive ( CUWApermitServerSRL ) tells CUWebAuth where to find the permit server for those pages that are restricted by permit.    You should not need to change this string unless CIT changes the location of the permit server.

Finishing Common Configuration

Once you have made any necessary edits to the common area of the httpd.conf file, you are ready to move on to specifying how to restrict specific resources on your web site.   There are more common configuration directives, they are outlined in the directive reference found later in this document.

Any time you modify the httpd.conf file, you will need to restart apache in order for the changes to take effect.    This is commonly done with the apachectl script found in the bin directory of your Apache tree.  

Setting Up Restricted Resources

Now that CUWebAuth is configured you are ready to start specifying how to restrict resources.   This is done, again, in the configuration file ( httpd.conf ).

CUWebAuth can be used in any “block” (Directory, Location, etc.) where you can specify authentication rules.

Example:   Directory Blocks

An example of a Directory block in which CUWebAuth restrictions are specified might look like this:

So what does this really mean?   When a URL is submitted by an end user, CUWebAuth will compare the path specified in the URL to the path specified in every Directory block in the configuration file.   If the path specified by the end user appears in the directory specified in the Directory block (or in a sub directory of the directory specified in the Directory block), the restriction rules specified in the Directory block will be applied before serving the page.    So,   given the directory block specified above, the following URLs would cause the rules in that directory block to be applied:

• http://yourserver/test/test.html
• http://yourserver/test/pictures/smile.jpg
• http://yourserver/test

Now that we’ve covered the cases in which the directives in a particular Directory block are applied before serving a page, let’s look at those directives…

The first directive ( AuthName ) should always be set to CORNELL.

The second directive ( AuthType ) can have one of the following values:  

• all
• all-force
• all-forceonce
• cuweblogin
• cuweblogin-force
• cuweblogin-forceonce
• inline

Using "all" is the most flexible in that it doesn't rely on any specific authentication method.  The “-force”  causes any cached Kerberos credentials to be forcibly cleared and the user will have to log in before gaining access to the resource.   The "-forceonce" insures that the user had to log in at least the first time they accessed the restricted resource.  If neither "-force", nor "-forceonce " is specified, then the user may have logged in some time ago (up to 8 hours in the past).  Which option you choose depends on the security requirements of your applications.  An example of a good reason to force a login is when the user is about to change important information such as personal contact or registration information.

The require directive is used to specify what type of restriction is applied to the directory.   The require directive can be followed by one of the following three keywords:  

• valid-user
• permit
• netid

The first of these ( valid-user ) is used to specify that any user who has a valid NetID may access files in the directory.   Please note that this is NOT recommended for any production usage concerning sensitive data at Cornell University . If you use valid-user , anyone with a non-expired Cornell Kerberos Principal can access your resource, regardless of whether or not they are actually an active user, have any valid permits, are in the Cornell Directory, etc.

The second ( permit ) is used to specify that the user must hold a valid permit in order to access the specified resource.   In this case the keyword permit is followed by a space separated list of permit names—if the user holds an one of those permits he/she is granted access.    

Finally, the third ( netid ) is used to specify that a particular NetID is allowed access to the individual file.   A space separated list of NetIDs follows this keyword.

These keywords may also appear multiple times within the directory block, but it is generally cleaner to have them appear once with a space separated list of either permits or NetIDs.   Here are some examples of valid require directives:

require valid-user

require permit cit.update.Eudora

require netid rd29 tcz3

In order for permit checking to work properly, the directive CUWApermitServerSRL must be set up properly as described earlier.     Your server’s Kerberos identity must also be authorized to look up whether or not an authenticated user holds that particular permit.

 

 
The CUWAproxyAllow directive is a relatively new addition to CUWebAuth.    It is used to control two new forms of authentication:

• Proxy authentication from another server, such as uPortal
• Direct authentication from fat clients or mid-tier servers.  

  This directive will be described in detail in the directive reference.   However adding the line:

            CUWAproxyAllow direct

will enable your web site to accept authentication from potential new web authentication clients currently in development.    If they are deployed, your web site will be ready to work with them from the date of their initial deployment.   There is no detriment to having this directive active if new web authentication clients are never released.  

Other “Blocks” from Apache
The Apache web server configuration file has other “blocks”   which may be specified such as “Location” or “Files”.   CUWebAuth for Apache supports all of them.    Please consult Apache documentation for more information on their use.

Conflicting “Blocks”
It is possible to have multiple blocks which are all valid matches for a particular URL.   Consider the following configuration file snippet:

<Directory /test/new>
...
</Directory>

<Location new>
...
</Location>

Now consider that the user requests the following URL:

            http://yourserver/test/new/index.html

This URL will actually match all three blocks above.    Which one is used to restrict the resource in this case?   Under CUWebAuth for Apache, the first one encountered (that matches) will be the “block” used to restrict the resource.   In this case it would be the directory block with the argument “/test/new” that would be used