NetBadge: Information for Developers and Server Administrators

[Nov 23, 2009 14:09] Web access to Microsoft Live@edu accounts now works.

This page presents information for developers who need to build or adapt applications to use NetBadge and 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. Apache (Unix) and Microsoft IIS can both be configured to use pubcookie. 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.

Apache/Unix Information

For 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

Note that if the application is based on PHP, then PHP puts the username in the variable $_SERVER['PHP_AUTH_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"}.

  • In the .htaccess file (or 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

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

    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.

  2. Design your application so that the browser uses GET when accessing the page that first triggers NetBadge authentication. Do not trigger NetBadge with a POST. Specifically, you do not want an unprotected page with a form that POSTS to a protected page.

    If NetBadge authentication is triggered by a POST then the pubcookie module cannot simply redirect you to the login server because then all the POST data would get lost. Instead pubcookie uses a more complex mechanism to send you to the login server without losing the POST data. The mechanism doesn't work very smoothly, however, and an extra web page with a "continue" button usually appears. NetBadge authentication works much more quickly and smoothly with a GET.

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

For 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:

  1. 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.
  2. 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.
  3. 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:

  1. 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.
  2. 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

  3. Create a file called pubcookie.conf in your apache configuration directory with these lines in it:

    <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 "/www/doc_ssl">
    PubcookieInactiveExpire -1
    </Directory>
    </IfModule>

    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.

  4. 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.
  5. 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 # not needed by Apache 2.x
    ...
    Include /www/conf/pubcookie.conf

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

IIS/Windows Information

On Windows servers running IIS, the first step is to install the Pubcookie ISAPI filter. Some configuration must be done in installing the filter, for which there is online documentation at http://www.pubcookie.org/docs/install-filter.html. There is one undocumented configuration change that must also be made: If you are running IIS 6, your web site runs within an application pool. To keep NetBadge authentication from timing out after a few minutes, you must go to the Properties of that application pool, bring up the Performance tab, and uncheck the idle timeout.

If an individual application has its own security module coded into it, that code must be removed in order for the application to work with NetBadge. Otherwise, just go to the Properties for the application's subsite, and find the tab with a drop-down box for Auth Type. The default is None; change to Net ID to make it use NetBadge. ITC recommends that when you install the Pubcookie ISAPI, you also install the test application that comes with it, to learn the basics of setting it up.

After setting up your Apache- or IIS-based application to use NetBadge, contact ITC's Unix Systems group to let them know you want your server to participate in NetBadge authentication, and they can make the necessary entries on their end.

© 2009 by the Rector and Visitors of the University of Virginia.

The information contained on the University of Virginia’s Department of Information Technology and Communication (ITC) website is provided as a public service with the understanding that ITC makes no representations or warranties, either expressed or implied, concerning the accuracy, completeness, reliability or suitability of the information, including warrantees of title, non-infringement of copyright or patent rights of others. These pages are expected to represent the University of Virginia community and the State of Virginia in a professional manner in accordance with the University of Virginia’s Computing Policies.