NetBadge at UVa
For IIS/Windows Developers and Server Administrators
This page presents information for developers who need to build or adapt Windows applications to use NetBadge, and IIS 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 UVa implementation of that technology.
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 Windows Web Application Developers
To use NetBadge the developer must contact the system adminstrator and ask that NetBadge be enabled for the website being developed. If the server is part of ITS's Windows Services, the developer may send an email to ITS Virtualization and Microsoft Services (VAMS).
With IIS, NetBadge authentication looks just like HTTP "Basic" authentication to the Web application. No additional coding is needed unless user information is needed for the application. In order to determine who has authenticated via NetBadge, the environment variable HTTP_PUBCOOKIE_USER must be read. HTTP_PUBCOOKIE_USER contains the user ID, and the contents should be placed into a session variable for reference. Once the user ID is determined, code can be written to determine any additional roles that may be assigned to the ID.
Any NetBadge application can be developed on a local desktop. If environment variable calls and session variables are needed, simply hardcode a value to allow development without NetBadge. Once the website is ready for testing on the deployment server, the environment variable calls can be tested and verified.
Required Logout Advisory
If you choose to incorporate UVa 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,
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 of a UVa-owned computer should have a password-protected screen saver enabled on the computer.
- 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.
Information for Windows System Administrators
All downloads and documentation can be found at http://pubcookie.org. The version tested at this point is ISAPI filter 3.3.1 with login server 3.2 running on Linux. The 3.0 ISAPI documentation is very helpful in verifying the correct registry edits are in place if necessary.
- The Web server must have an SSL certificate. All Pubcookie activity is via SSL.
- The Web server should have the UVa root and intermediate certificates installed to the local machine certificate store.
- ITS Systems and Storage Services must create a crypt key file for the server. This file will be named the server's FQDN for the Web host. (the URL name) Send an email to email@example.com to request this file.
- Time on the client server should be synched to the same source as the login server.
- Prior to installation make sure ITS Systems and Storage Services has all that is needed for setup on NetBadge, and all is in place.
- Prior to installation make sure time on the Web server is synched to time.virginia.edu
- During the ISAPI filter installation you will be asked for
- Login URL: https://netbadge.virginia.edu/
- Key Server URL: https://netbadge.virginia.edu:2222 This information can be entered, however, the key client step is no longer needed since ITS Systems and Storage Services has already sent the file via email. The key client file and the granting cert files should be placed in the c:\WINDOWS\system32\inetsrv\pubcookie\keys folder.
- After installation the enterprise domain should be set to .virginia.edu in the Pubcookie Directives for the server.
- Pubcookie supports 3 authentication flavors, but comes with only one defined — NetID. This requests an ID/password pair. Name the second flavor UVaAuth or something else meaningful. This should be the authentication flavor selected for site protection. It allows the user to authenticate via certificate or ID/password pair.
- The ISAPI installer will create and install a Pubcookie3 filter at the Web root. This may cause instability if other ISAPI filters are loaded, such as ASP.Net. You can move the Pubcookie filter to a lower level. It appears to fix the instability.
- On any Web application pool running a Pubcookie site, the Shutdown Idle Worker Process check box should be unchecked. This is found on the Performance tab.
- A Web service extension must be created and allowed for Pubcookie.
- In IIS, on the protected folder properties, Directory Security tab, under the Secure Communications section, click Edit. Make sure Ignore Client Certificates is checked.
- Set the encryption type to AES in the Pubcookie Directives which should be the default. DES is supported, but AES is preferred.
- Set the Idle Time Out in the Pubcookie Directives to 28800 for any site where the user may be filling out forms that take time. Be aware this will require additional memory allocation on the Web server.
- For Pubcookie protected sites on the Pubcookie Directives tab the Error_page value should be set to a custom created error page. Otherwise, up on error the user is shown a page that says Authentication Error: please contact ntadmin@servername (where server name is the name of the server).
- Cold Fusion sites that will be Pubcookie enabled must have IIS WPG (the IIS Worker Process Group) added to the site's ACLs with Read/Execute permissions on the application side, and Read/Write/Execute on the database side.
- If your Web server hosts multiple sites please make sure to follow the instructions at: http://pubcookie.org/docs/install-filter.html#vhosts.
- Servers located behind the Joint VPN cannot have Pubcookie authentication at the root—it must be set on a subfolder.
It has been verified, at least with ColdFusion, that subfolders within a site that contain includes and/or images, or other components called by the code, rather than directly by the client's browser, must be un-pubcookie protected for the application to work. This has not been tested or verified with ASP or .Net.
Pubcookie implementation on virtual hosts:
- Manually add the ISAPI filter to the virtual host's filter list
- Uncheck the Shutdown worker processes on the Performance tab of the application pool
- Follow the instructions at http://pubcookie.org/docs/install-filter.html#vhosts to create a subkey under Pubookie in the registry, and set the WebVarLocation on the Pubcookie Server Values tab
- Request a NetBadge set up for the virtual host's name as it appears on the certificate from ITS Systems and Storage Services. Place the crypt key file in the c:\WINDOWS\system32\inetsrv\pubcookie\keys folder.