Table of Contents
Information for Windows Web Application Developers
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.
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 ITC's Windows Services, the developer may send an email to itc-microsystems@virginia.edu.
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 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.
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.
- Prerequisites:
- 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.
- Unix Systems must create a directory on Netbadge for the server. This directory would be named the server's FQDN.
- Netbadge must have the server's root certificate and any intermediate certificates. This should be sent to Unix in base 64 format (a pem file).
- Time on the client server should be synched to the same source as the login server.
- Implementation:
- Prior to installation make sure Unix Systems 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
the following:
- Login URL: https://netbadge.virginia.edu/
- Key Server URL: https://netbadge.virginia.edu:2222
- 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 DES in the Pubcookie Directives (the default is AES).
- 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.
Application notes:
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
- Verify that the website's certificate is one already on Netbadge, or supply the root to Unix Systems
- Request a Netbadge setup for the virtual host's name as it appears on the certificate
- Once the login server setup is complete, manually run keyclient:
C:\> cd C:\WINNT\system32\inetsrv\pubcookie
C:\> keyclient.exe -H appserver.example.edu -K netbadge.virginia.edu:2222