NetBadge: Information for Unix/Apache Developers and Server Administrators

This page presents information for developers who need to build or adapt Unix applications to use NetBadge, and Apache web server administrators who need to work in the NetBadge environment. The terms "Pubcookie" and "NetBadge" will be used, respectively, to denote the underlying authentication technology and the U.Va. implementation of that technology. Find more information about Pubcookie at http://www.pubcookie.org/.

In configuring an application to use NetBadge, the first step is to use a web server that has the pubcookie module installed. Once the web server has been installed and configured, then the web server itself handles the NetBadge authentication magic. The web application does not need to do any authentication at all.

Information for Unix Web Application Developers

On Apache, NetBadge authentication looks just like HTTP "Basic" authentication to the web app. The environment variable $REMOTE_USER contains the user name. With Apache, NetBadge authentication is enabled on a directory with an .htaccess file, just like "Basic" auth:

AuthType NetBadge require valid-user PubcookieAppId myappid

Note that if the application is based on PHP, then PHP puts the username in the variable $_SERVER["REMOTE_USER"]. If you are writing a CGI script in perl, on the other hand, you access the $REMOTE_USER environment variable as $ENV{"REMOTE_USER"}.

Setting the appid

In the .htaccess file (or <Directory> or <Location> directive) always set the appid:

PubcookieAppId myappid

You can have spaces in the appid if you enclose in double quotes:

PubcookieAppId "My App Id"

If you do not set the appid then pubcookie makes one up from the URL of your page. Depending on what URL people use to access the page, they may end up with multiple session cookies, which can cause extra trips to the login server and problems such as images failing to load.

Retrofitting an application to use NetBadge usually means discarding any code that authenticates a user. If an application has an HTML form for entering a username and password, it should be eliminated. Instead, the user name should be obtained from $REMOTE_USER.

Additional Notes

Pubcookie only does "authN", which identifies who the user is. It does not do "authZ", which determines what privileges, if any, the user has. If a web application is intended for use by only a certain group of people, then the web application will still need to decide if $REMOTE_USER is a member of that group. So web applications may need to do LDAP lookups to see if $REMOTE_USER is a member of the applicable authorized group. Of course, the web application could look up $REMOTE_USER in its own internal list of allowed users.
On Apache the .htaccess file provides a standard mechanism for restricting access, which works just like "Basic" authentication:

AuthType NetBadge require user scl ehc jbb PubcookieAppId myappid

Here all users who try to access the directory are authenticated by NetBadge, but then only scl, ehc and jbb are allowed into the directory and others get an "access denied" message.
We do not recommend protecting your SSL document root with NetBadge, such that browsing a URL like https://myhost.virginia.edu/ requires NetBadge authentication. Users may see error messages indicating problems with the pre-session cookie. This happens because browsers make extra requests to get files such as favicon.ico from the document root, triggering an extra NetBadge authentication, which causes confusion.
If you insist on having your SSL document root protected by NetBadge, then you should place a favicon.ico file there. The pubcookie module special cases this file and allows access to it without authentication. But this only seems to work properly if the file exists.

If the Internet Explorer browser has Content Advisor (CA) enabled, then it may be impossible to access anything beneath your SSL root document. This happens because CA looks for special headers in a document that indicate if the document contains questionable content. If the document does not have these special headers, then CA requests the root document, triggering an extra authentication, which interferes with the previous one.

Both of these problems can be avoided if your SSL document root does not require NetBadge authentication and you place all NetBadge authenticated content in sub directories rather than the SSL root directory.
You can configure the pubcookie module to cause your browser to delete the session cookie for a given application. Create a directory called "logout", for example, beneath the directory where NetBadge authentication is activated. Put a .htaccess file with the following contents in the logout directory:
PubcookieEndSession on

Also create a file called "logout.html", for example, with a logout message. Put a link to logout/logout.html in your application. When you click this link you will see the logout message and your browser will delete the session cookie. This has no effect on the login cookie or any other session cookies.

Information for Apache Web Server Administrators

If your web server is administered by ITC, then ITC handles the tasks outlined below. In that case you can send email to ITC Unix Systems (systems@virginia.edu) to see if the pubcookie module has been installed on your web server. If so, you need only follow the instructions for web application developers (above).

Requirements:

Pubcookie requires SSL, so apache must be configured to support SSL, and therefore you must have a host certificate. If you do not have a certificate then you can obtain one from http://standard.pki.virginia.edu.
Pubcookie requires that your browser accept cookies from the web server and pass them on to the NetBadge login server and vice versa. Your browser will not do this unless your web server hostname is under the virginia.edu domain.
Your web server must keep accurate time. If your system clock is more than 60 seconds ahead of the NetBadge login server's clock, then granting cookies from the login server appear to be expired on your web server. This sets up a loop wherein the browser is sent back and forth between the web server and the login server.

Installing and configuring the pubcookie apache module:

Send email to the ITC Unix Systems group at systems@virginia.edu and let us know what version of apache you are running and on what kind of system. ITC may have a module already built that you can use. We'll send it to you and you can simply copy it into the directory that holds your other apache modules.
If ITC does not have a suitable module already built for you, you should probably build pubcookie from our source code, since we have a few local modifications. ITC will make arrangements for you to get our code. We can also send you the symmetric key file and granting cert file specified below.
If you need to build from source, run these commands in the pubcookie source directory:

./configure make make install
Create a file called pubcookie.conf in your apache configuration directory with these lines in it:
Apache 1.3.x:

<IfModule mod_pubcookie.c> PubcookieGrantingCertFile /usr/local/pubcookie/keys/pubcookie_granting.cert PubcookieSessionCertFile /www/cryp/STAR_ITC_cert.pem PubcookieSessionKeyFile /www/cryp/STAR_ITC_key.pem PubcookieKeyDir /usr/local/pubcookie/keys PubcookieDomain .virginia.edu PubcookieAuthTypeNames Pubcookie NetBadge PubcookieLogin https://netbadge.virginia.edu/ # Disable inactivity timeout by default in DocumentRoot <Directory "/"> PubcookieInactiveExpire -1 </Directory> </IfModule>

Apache 2.x:

LoadModule pubcookie_module modules/mod_pubcookie.so PubcookieGrantingCertFile /usr/local/pubcookie/keys/pubcookie_granting.cert PubcookieSessionCertFile /www/cryp/STAR_ITC_cert.pem PubcookieSessionKeyFile /www/cryp/STAR_ITC_key.pem PubcookieKeyDir /usr/local/pubcookie/keys PubcookieDomain .virginia.edu PubcookieAuthTypeNames Pubcookie NetBadge PubcookieLogin https://netbadge.virginia.edu/ # Disable inactivity timeout by default in DocumentRoot <Directory "/"> PubcookieInactiveExpire -1 </Directory>

You need to modify some of the file names above. The PubcookieSessionCertFile is your host certificate and the PubcookieSessionKeyFile is the corresponding private key. Change /www/doc_ssl to your SSL document root directory.
The ITC Unix Systems group must configure the NetBadge login server to allow your web server to use it. Send an email to systems@virginia.edu and provide the hostname of your web server. We will send back a symmetric key file and a granting cert file.
- You must put the symmetric key file in the PubcookieKeyDir directory and give it the same name as your web server's hostname. You must use all lower case letters in the file name. For security, this file should be owned by the user under whom apache runs, and should have permissions 600 (read/write for owner, noaccess for anyone else).
- You must also name the granting cert file with the name specified by PubcookieGrantingCertFile. This file can be world readable.
- Although pubcookie includes a program called "keyclient" to obtain the symmetric key and granting cert, our network has a firewall that prevents most users from using it. Furthermore, even if you can access it you have to configure keyclient properly. It's easier just to get these files by email.
If you are running Apache 1.3.x, edit your apache configuration file (usually httpd.conf) to load the pubcookie module and to include the pubcookie.conf file:
LoadModule pubcookie_module libexec/mod_pubcookie.so ... AddModule mod_pubcookie.c ... Include /www/conf/pubcookie.conf

In Apache 2.x you do not need to modify your httpd.conf file at all, because it probably contains this line:

Include /etc/httpd/conf.d/*.conf

This includes all configuration files that match the above pattern. Simply installing your pubcookie.conf file in the conf.d directory will cause httpd.conf to Include it.
You usually use a .htaccess file to configure a directory for NetBadge authentication. If you want to allow .htaccess files then you need to configure apache to pay attention to them. At a minimum you need this statement:
AllowOverride AuthConfig
Stop and start your apache server. If it fails to start, check your apache error log to see what went wrong. You probably have an error in the pubcookie configuration.
Once apache is running you can test pubcookie.
- Create a directory under your SSL document root and include the following in a .htaccess file:
  AuthType NetBadge require valid-user PubcookieAppId netbadgetest
- Put an HTML document in the same directory, completely exit and restart your browser, and try to access the document. You should be directed to the NetBadge login page. Once you have logged in, the document should display and you should be able to access it again later without logging in.

Required Logout Advisory

If you choose to incorporate U.Va. NetBadge functionality in your application, you must include an advisory on the logout page like the one shown below. While it is not necessary to adopt the precise language shown, you must address all points covered here.

WARNING: Protect your privacy! Prevent unauthorized use!

Exit your Web browser completely (quit the web browser) when you are finished using it to access NetBadge-enabled applications (e.g. WebMail, Portal, etc.).
Follow this link for detailed instructions >>.
If you have a digital certificate on your computer, you must logoff or restart your computer to end your NetBadge session or enable a password-protected screen saver to prevent someone else from using your certificate credentials to obtain a NetBadge. Every user should always have a password-protected screen saver enabled on their computer for a variety of reasons.
If you are using an Internet kiosk and are unable to exit the Web browser, please follow this link for instructions that use the logout button to accomplish most of the logout functionality that you would normally achieve by exiting from your web browser.

For: