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 “Shibboleth” and “NetBadge” will be used, respectively, to denote the underlying authentication technology and the UVa implementation of that technology.
If you are configuring an application running on Windows 2008 or Windows 2012 to use NetBadge, the first step is to use a Web server that has the Shibboleth 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.
If configuring an application running on an existing Windows 2003 server, follow these instructions relating to older Windows operating systems.
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_UID must be read. HTTP_UID 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.
Other default variables available to the developer are HTTP_AFFILIATION and HTTP_UNSCOPEDAFFILIATION. These variables allow the developer to determine the status of the authenticated user (Faculty/Staff/Student).
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://shibboleth.net. The version tested at this point is ISAPI filter 2.5.0.
The IIS website must have an appropriate x509 certificate installed and SSL enabled. In addition, IIS 6 Management Compatibility must be installed on IIS 7.x/8.x since the Shibboleth installer package uses those management interfaces. The IIS 6 Management Compatibility option can be installed from Administrative Tools > Server Manager > Roles > Web Server (IIS) > Role Services. In addition, the ISAPI support and CGI modules must be installed.
- Run Windows installer
- Download the latest version of the Windows installer package from the Shibboleth download site at http://www.shibboleth.net/downloads/service-provider/latest/.
- Run the installer package. It is recommended that you accept all defaults, as follows:
- Accept the license agreement
- Install to C:\opt\shibboleth-sp
- For 64-bit installer packages, Run as 32-Bit is unchecked unless you will use Shibboleth with a 32-bit application pool (option does not apply to 32-bit installer packages)
- Install ISAPI modules into IIS is checked
- IIS Script Extension is ".sso"
- Click Next, then Install, then Finish
- Click Yes to restart your system
- Verify installation
- On the Administrative Tools menu, click Services. Find Shibboleth 2 Daemon in the list and double-click it. Verify that Service Status is Running, Startup type is Automatic, and on the Log On tab, verify that Local System is selected.
- Open IIS Manager and verify the Shibboleth ISAPI filter is installed:
Click on the name of your server in the left navigation pane, and click ISAPI Filters in the center pane. In the list should be filter with the Name Shibboleth and the Executable C:\opt\shibboleth-sp\lib64\shibboleth\isapi-shib.dll (for a 64-bit install — 32-bit install will have a slightly different path).
- Also in IIS Manager, verify that the Shibboleth ISAPI filter is mapped to the .sso extension:
Click on the name of your server in the left navigation pane, and click Handler Mappings in the center pane. Find the entry for shibboleth. Verify Path is *.sso, State is Enabled, Path Type is Unspecified, Handler is IsapiModule, and Entry Type is Local.
Note: In some cases it appears that the handler mapping is not inherited down to the website level. If this happens Shibboleth will not work. To check this, click on your website name under Sites, then open Handler Mappings. Click Handler Mappings in the center pane. Find the entry for shibboleth. Verify Path is *.sso, State is Enabled, Path Type is Unspecified, Handler is IsapiModule, and Entry Type is Inherited.
If the *.sso entry mapping is missing you need to create it in one of two ways:
- Only for a handler mapping that is not being inherited down
If none of your site handler mappings have an Entry Type of Local, click Revert to Parent in the Handler Mapping Action pane (far right pane). This copies all mappings down from the server level and will delete any local mappings at the website level. If you have local mappings configured, use the method described next.
- For missing parent or child handler mappings
Create the mapping manually by clicking Add Script Map in the Handler Mapping Action pane (far right pane). For Request path, type *.sso, for Executable, type C:\opt\shibboleth-sp\lib64\shibboleth\isapi-shib.dll (for a 64-bit install — 32-bit install will have a slightly different path), for Name, type shibboleth (in rare circumstances you may need to use a different name). Click Request Restrictions... and on the Mapping tab, uncheck Invoke handler only if request is mapped to:.
- Only for a handler mapping that is not being inherited down
- Open a Web browser on the server and go to https://localhost/Shibboleth.sso/Status (URL is case sensitive). Do not substitute your server's full domain name in place of "localhost". You should get back an XML document with <Status><OK /></Status> at the bottom.
- Configure the shibboleth2.xml file.
- Contact Enterprise Infrastructure-Systems & Storage Support and let them know you want to add the server to Shibboleth. Complete the form to add the entityID of your SP; EI-SSS will retrieve the server metadata and add it to the Shibboleth IDP. Also inform them that the server needs to receive the assertions containing the user computing ID. By default Shibboleth does not return any assertions.
- Run Windows installer
Adding Shibboleth Authentication to a Web Application
Please be sure to configure the Shibboleth2.xml file described in step 3 above before proceeding further. Your Shibboleth installation must be working before attempting these steps.
- The Shibbolethh configuration file can be found at c:\opt\shibboleth-sp\etc\shibboleth\Shibboleth2.xml. Make a backup copy of the file before making any changes. A typo in this file will cause everything to stop working.
- Look for the RequestMapper element in Shibboleth2.xml shown below. The example
below shows two sites already protected by Shibboleth; they are named secure and
The example requires a session for documents in /secure on the containing
host with http and https on the default ports. Note that the name and port
in the <HOST> elements MUST match Apache's ServerName and Port directives or
the IIS Site name in the <ISAPI> element above.
<Path name="secure" authType="shibboleth" requireSession="true"/>
<Path name="secure2" authType="shibboleth" requireSession="true"/>
<!-- Example of a second vhost mapped to a different applicationId. -->
<Host name="admin.example.org" applicationId="admin" authType="shibboleth"
- Copy and paste an additional Path Name section under the existing Path Name elements.
- In the Path Name = "" section, type the name of your application as it displays in IIS.
For example, if your new Web application is named MySite the element would look like this:
<Path name="MySite" authType="shibboleth" requireSession="true"/>
- Once the change has been made you must restart the Shibboleth 2 Daemon service. If the service does not restart there is most likely a typo in the Shibboleth2.xml file.
- Restart IIS by running the iisreset command from the command line.
- To remove Shibboleth protection, delete the Path name = element for the specific Web application and restart the Shibboleth 2 Daemon and IIS.