Skip to content »
ITS and UVa logos for printed output
MENU

NetBadge at UVa

Information for Developers & Server Administrators

NetBadge Info for UNIX/Apache httpd Developers

NetBadge authentication looks just like HTTP “Basic” authentication to the Web app. The Pubcookie module authenticates the user and passes the username to the app in the $REMOTE_USER environment variable. The app never receives an unauthenticated request and all requests include $REMOTE_USER.

If you are using PHP, then the username is in $_SERVER['PHP_AUTH_USER'], and if you are using Perl, then the username is in $ENV{"REMOTE_USER"}.

NetBadge authentication is usually enabled in a directory by installing an .htaccess file like this:

AuthType NetBadge
require valid-user
PubcookieAppId myappname

Or else you can put these lines into an Apache httpd configuration file surrounded by <Location>, <Directory>, or <Files> directives. In fact, you cannot use an .htaccess file when a URL does not map to a physical directory.

  • The AuthType and require directives enable authentication. AuthType can be NetBadge for standard login or EnhancedNetBadge for Enhanced NetBadge login.
  • The require directive determines who can access the resource. require valid-user allows any authenticated user to have access. You can restrict access to a list of users with require user abc def ghi. This restricts access to the users abc, def, and ghi. And you can use require directives provided by mod_authnz_ldap such as require ldap-group cn=mygroup,ou=Groups,o=University of Virginia,c=US.
  • PubcookieAppId sets the application id, which determines the name of the session cookie. If you have several related applications in different directories, then you can give them all the same appid so that the user can access them all with one session cookie, which is more efficient than separate cookies. The appid may contain spaces if you enclose it with quotes: PubcookieAppId "My App Name"

Additional Notes & Recommendations

  • 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, then it should be eliminated. Instead, the user name should be obtained from $REMOTE_USER.
  • Pubcookie only does “authN,” which identifies who the user is. It does not do “authZ,” which determines what privileges, if any, the user has. So a Web application may need to consult an internal user database or query LDAP to determine what $REMOTE_USER is authorized to do. Beware that many non-UVa people (guests, contractors, etc.) can login to NetBadge. If you use require valid-user and do not restrict access further, then non-UVa people can access your application.
  • Avoid enabling NetBadge in "/" (the document root directory). You might run into problems because browsers make hidden requests for files in "/" such as /favicon.ico. It is better to enable NetBadge in subdirectories.

NetBadge Info for Web Server Administrators

If your Web server is administered by ITS, then ITS handles the tasks outlined below. In that case you can send email to ITS Systems and Storage Services (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 httpd must be configured to support SSL, and therefore you must have a host certificate. If you do not have one, obtain a certificate.
  • 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 an endless loop wherein the browser is sent back and forth between the Web server and the login server.

Installing & Configuring the Pubcookie Apache Module

  1. Send email to the ITS Systems and Storage Services group at systems@virginia.edu and let us know what version of Apache httpd you are running and on what kind of system. ITS may have a module already built that you can use. For recent releases of RedHat Fedora Linux we have a mod_pubcookie RPM.
  2. If ITS does not have a suitable module already built for you, then you should build Pubcookie yourself. Obtain the source code from the Pubcookie website.

    Run these commands in the Pubcookie source directory:

    ./configure
    make
    make install

  3. Create a file called pubcookie.conf in your Apache httpd configuration directory (usually /etc/httpd/conf.d) with these lines in it:
    LoadFile /usr/lib64/libcrypto.so
    LoadModule pubcookie_module modules/mod_pubcookie.so
    PubcookieGrantingCertFile  /usr/local/pubcookie/keys/pubcookie_granting.cert
    PubcookieSessionCertFile   /etc/pki/tls/certs/STAR_ITS_cert.pem
    PubcookieSessionKeyFile    /etc/pki/tls/private/STAR_ITS_key.pem
    PubcookieKeyDir            /usr/local/pubcookie/keys
    PubcookieDomain            .virginia.edu
    PubcookieAuthTypeNames     Pubcookie NetBadge EnhancedNetBadge
    PubcookieLogin             https://netbadge.virginia.edu/
    PubcookieLoginMethod       POST
    
    # Disable inactivity timeout by default.
    
    <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. You may not need the LoadFile line. On 32-bit Linux systems, libcrypto.so is in /usr/lib.

  4. The ITS Systems and Storage Services 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. This is the hostname that appears in URLs such as https://some.host.edu/... 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 the hostname that appears in URLs. You must use all lower case letters in the file name. For security, this file should be owned by the user under whom Apache httpd runs (usually “apache”), and should have permissions 600 (read/write for owner, no access for anyone else).
    • If PubcookieSessionCertFile has a subject CN other than the hostname in your URLs, such as when using a wildcard certificate, then you must create a symbolic link to your symmetric key file with the same name as the Subject CN of the certificate. For example, when using the *.virginia.edu wildcard certificate, you must create a symbolic link named *.virginia.edu (literally).
    • 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, we don’t support it and distribute these files via email instead.
  5. Stop and start your Apache httpd server. If it fails to start, check your error log to see what went wrong. You probably have an error in the Pubcookie configuration.
  6. Once Apache httpd is running, you can test Pubcookie.
    • Create a directory under your SSL document root and install an .htaccess file as described above.
    • 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.

  Page Updated: 2013-02-26