Configuring CUWebAuth for IIS

Once you have CUWebAuth successfully installed, it’s time to begin the process of configuration. Configuring CUWebAuth involves two main areas:

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 is 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.

Your installation of CUWebAuth comes with a “test” srvtab you can use for testing purposes. When your site is ready to enter a production phase you should obtain a dedicated 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. In the meantime, you can use the test srvtab. The identity stored in the test srvtab is as follows:

mandarin-agent.test

CUWebAuth will need to know where the srvtab file containing this identity is located on your machine. The default test.srvtab file is installed to your CUWebAuth folder, and is the one initially specified in the CUWebAuth.conf file . NOTE: the path of this initial test srvtab is assumed to be C:\WINNT\CUWebAuth , so if you changed this install folder during initial setup, be sure to change the path declared in the CUWebAuth.conf file as well.

If you do not yet have a production srvtab on your machine and wish to begin by using the test identity, verify the path to the srvtab file that comes in the CUWebAuth distribution in CUWebAuth.conf . It should be noted here that a srvtab really is a cached id and password for your server, so access to the machine and its WINNT folder should be secure enough for only Administrators of the server to access or overwrite it.

When you eventually get your new production srvtab and identity, simply change the corresponding lines in the CUWebAuth.conf file and restart IIS.

Register to use CUWebLogin

If you wish to use CUWebLogin as an authentication mechanism, your server’s ServiceID and IP address must be registered with the CUWebLogin server before you will be able to authenticate users this way. If for some reason your ServiceID is not registered to use CUWebLogin, please send mail to aadssupport@cornell.edu and provide your ServiceID (the Kerberos principal assigned to your server) as well as the IP address (NOT DNS name) of the server that needs to be registered.

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

Editing the CUWebAuth.conf File

The CUWebAuth distribution contains a file called CUWebAuth.conf , which contains the standard configuration directives needed for CUWebAuth and a sample <Directory> block with generic restrictions on it. The file looks something like this:

            CUWAkerberosPrincipal mandarin-agent.test
            
            @CIT.CORNELL.EDU
            
            CUWAsrvtabPath        C:\WINNT\CUWebAuth\test.srvtab 

            CUWAcuwlServerSRL     ipHost=cuweblogin.cit.cornell.edu ipPort=1010
            netid=erpcd.webster authent=k4 

            CUWAcuwlServerSRL     ipHost= cuweblogin2.cit.cornell.edu ipPort=1010
            netid=erpcd.webster2 authent=k4 

            CUWApermitServerSRL   ipHost=permit1.cit.cornell.edu ipPort=756 netid=permitd.permit1
            authent=k4 

            CUWAdebuglevel        normal 

            CUWAcookiedomain      cornell.edu 

            <Directory /test> 

                AuthName         CORNELL 

                AuthType         all 

                require          valid-user 

                CUWAproxyAllow   direct 

            </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, or you can use the test srvtab provided with the CUWebAuth distribution.

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.

The fifth directive (CUWAdebugLevel) tells CUWebAuth how much information per transaction to put in the CUWebAuth.log file. The default is normal, which will produce minimal logging.

The final directive (CUWAcookieDomain) tells CUWebAuth what domain to assign in the outbound cookies that are used to communicate with the users’ web browsers. This must match the root domain of the DNS identity for your server, otherwise the cookie will usually be rejected by web browsers. If your server is on Cornell’s campus, it must be within the cornell.edu domain and thus this directive need not be changed. Consult your departmental network administrator or the NOC if you are unsure of your server’s DNS identity.

Finishing Common Configuration

There are more common configuration directives you may wish to add to your file, which are outlined in the directive reference found later in this document.

Any time you modify the CUWebAuth.conf file, you will either need to restart IIS or access ReloadConf.html in order for the changes to take effect. Make sure that you restrict this file on your webserver. The default CUWebAuth.conf file that is provided by the installer has a location directive for this purpose. Change the require netid directive to the netid of the web-admin.

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 ( CUWebAuth.conf ).

Restrictions are assigned in CUWebAuth by use of the “block” syntax used in Apache configuration files. A block consists of:

an opening tag (like with HTML code, it is bracketed in < >’s) specifying the type of restriction (e.g. Directory ) and the resource (e.g. a URL path string)
a list of block-specific directives
a closing tag in < > brackets with a “/” followed by the same restriction type as the opening tag (e.g. < /Directory> ).

Example: Directory Blocks

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

            <Directory /test> 

                AuthName CORNELL 

                AuthType all 

                require valid-user 

                CUWAtimeout inactivity 

                CUWAproxyAllow direct 

            </Directory>

So what does this really mean? When an end user submits a URL, 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 six 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.

So why isn’t this the default behavior? While forcing credentials gives you some added confidence that the real end user is the one contacting your server, it is very annoying to the user and desensitizes them to the act of entering their password. The idea behind Kerberos is that you treat your password as a sacred entity—entering it only when absolutely necessary and being very cautious about where you are entering it. When applications (web and otherwise) begin forcing the credential cache so that the user has to keep entering his/her password all the time, users become desensitized to that act and become annoyed at the constant prompting. Why? Because even though you’ve cleared their credentials cache for the sake of your application, they may also be prompted again for other services (mail, other custom apps) that might need credentials as well. As such you are strongly discouraged from using the “-force” directives unless you feel it is absolutely necessary.

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 one of those permits he/she is granted access.

Finally, the third ( netid ) is used to specify that a particular NetID be 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 ss488 pb10

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.

A note about Permits…

In general, permits are owned by individuals who must give specific access to servers to lookup whether or not a particular user holds that permit. This is done by contacting the permit owner and asking to have your server’s Kerberos identity added to the list of identities authorized to perform lookups against that permit. Remember, your server’s Kerberos identity is the “srvtab name” you asked for. Please do not ask a permit owner to grant lookup access to the test identity ( mandarin-agent.test ). There are some permits which are considered “public” and anyone may lookup whether or not a particular user holds that permit. Two examples are cu.student (is the holder of this NetID a student) and cu.employee (is the holder of this NetID a staff/faculty member).

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.

Location Blocks

A location block is similar to a directory block except that an incoming URL will be restricted if the string specified contained in the URL requested, regardless of what directory it is in. An example of a Location block follows:

AuthName CORNELL
AuthType all
require valid-user

</Location>

As you may notice, this is very similar to a Directory block. However, notice the argument in the opening “Location” tag. If any URL contains the word “test”, it will match up with this directory block. Therefore, the following URLs would match:

http://yourserver/incoming/test/foo
http://yourserver/mytest/inter.html

The directives that may appear in the Location block are the same as those in the Directory block. Please consult that section for more information.

Other Blocks from Apache
The Apache web server configuration file has other “blocks” that may be specified such as “Files”. CUWebAuth for IIS currently only implements “Directory” and “Location”.

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

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 IIS, 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.