by Leroy Altman
As you may have heard, Stanford is moving away from their in-house created authentication software known as “WebAuth” to an industry standard Open Source technology called SAML2. Software called “Shibboleth” is available to leverage SAML2 and it includes a version created for Microsoft’s Internet Information Server (IIS) web server running on Windows.
This article was gathered from two great sources listed below, and I encourage you to read both for more details. This article is really just the tip of the iceberg:
- The main Shibboleth community: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPWindowsInstall
- University Of Missouri’s IT department: https://doit.missouri.edu/wp-content/uploads/2014/09/WindowsGuide.pdf
There are two new terms to know:
- Identity Provider (IDP): This is Stanford’s central authentication service
- Service Provider (SP): This is your web server
Installation: This is a quick summary of how to get Shibboleth installed and working on a Windows IIS web site.
- Windows Server 2012 R2 w/ IIS installed.
- In addition to the default IIS modules, you’ll also need to add Management Compatibility components:
- IIS 6 WMI
- IIS 6 Metabase compatibility
- IIS 6 Scripting tools
- IIS 6 Management Console
- Install ISAPI filter and Extensions [located in Web Server (IIS) → Web Server → Application Development]
- A “Default Web Site” which has a default page, used for testing.
- A “/secure” subfolder under the root, also with a test page.
- An SSL certificate installed and working on the website.
Run the Shibboleth Installer. The most recent version, as of this writing, is here: https://shibboleth.net/downloads/service-provider/2.6.1/win64/
The defaults for installation are typically fine to use:
- Installation path – C:\opt\shibboleth-sp\
- Install ISAPI modules into IIS
- IIS Script extension “.sso”
Reboot when completed.
Verify that Shibboleth was installed successfully. On the server, using Internet Explorer, browse to: https://127.0.0.1/Shibboleth.sso/Status. It provides an XML page with detailed info on Shibboleth and SAML. (Take note that the URL path shown above is case sensitive.)
Next, test the default Shibboleth functionality:
- Open a command prompt
- Navigate to C:\opt\shibboleth-sp\sbin
- Run: shibd.exe -check
Look for “overall configuration is loadable” in the output to indicate success.
Now we will edit the Shibboleth2.xml file, located in C:\opt\shibboleth-sp\etc\shibboleth, to customize it for your server needs. Friendly suggestions: To help with editing, use a utility like “Notepad++” that provides code-style display of XML code. (Please make sure you “Run as admin”.) Also, things can “break” easily, so it’s best to make one change at a time and then test…
- Save the file
- Restart IIS (iisreset.exe)
- Restart Shibboleth service
- Test via:
- Status page: https://127.0.0.1/Shibboleth.sso/Status
- Opt file test: shibd.exe -check
Replace the “name=”sp.exapmple.org” with your server’s FQDN. Save and restart IIS and Shibboleth service, and do above two tests.
In the “<InProcess” section, edit the name in the “<Site id=” line (Note: the Site ID is equal to the IIS web page “ID” #. The “Default Web Site” uses “1”. Additional sites will use others.)
Example: <Site id=”1” name=myserver.stanford.edu”/>
Edit “Host name….” in “<RequestMapper..” replacing sp.example.org with your FQDN.
Leave “<Path name=’secure”…” for testing. (Note: this allows your root page be be anonymous, but Shibboleth authentication will be required when you got to “\secure” will subfolder.)
Edit “<ApplicationDefaults…” to remove the default and add your FQDN. Leave the “https:” and “../shibboleth” parts
SSO entityID Section for Stanford’s IDP information
Edit “<SSO entityID…” removing the default URL and the “idp/shibboleth” path so that line should just read:
Simplest way is to leave whole section commented out (its default state) and add this line:
<MetadataProvider type=”XML” uri=”https://idp.stanford.edu/metadata.xml” backingFilePath=”shib-federation-metadata.xml” reloadInterval=”7200”/> </MetadataProvider>
That completes the edits, run the above tests one final time to make sure everything is valid.
Now we need to extract the “SP” Metadata File (I.e. from the web server)
(Before starting, be sure that you’ve restarted the Shibboleth service after any changes so that it gets included.)
Using Internet Explorer on the server… add “https://[your FQDN]” to “Trusted Sites”, then browse to this path using the FQDN: https://FQDN/Shibboleth.sso/Metadata
… you’ll get a download option. Save the file, and then submit it to Stanford’s Service Provider submission page: https://SPDB.stanford.edu
Once your Metadata has been added to Stanford IDP, you’ll have a web site responding like this:
- https://FQDN/ ← Available to anyone
- https://FQDN/secure ← Prompts for SUNet ID, two-factor login
In the real world, a 3rd party vendor may have specific parameters for the Shibboleth2.xml file that allows authentication for their software. Those changes most likely will be in the “Request Mapper” section.