Installing SP2.x under Windows

This set of instructions are for IIS on Windows. Instructions for Apache on Windows will follow.

IIS Install Requirements

IIS6:

You will just need the basic website modules (Common files, Internet Information Services Manager and World Wide Web Service) which contains all the elements required to run the Shibboleth module.

IIS7:

IIS7 on Server 2008 is a highly modular install and has many different components, many of which you do not need. Open Server Manager and select roles. As a minimum you will need;

Web Server IIS

ISAPI Extentions

ISAPI Filters

IIS 6 Management compatibility (required to installed Shibolleth SP using the installer)

IIS Configuration

Once installed you need to configure your site and check to make sure that it works as a web site and to either use the default folder of /secure to store protected content or to use another folder. For pre-existing web sites bear in mind where you want the restrictions to your site to be, as the default restricted folder is /secure, you will need to configure your shibboleth2.xml to reflect your sites structure and secure requirements.

Shibboleth2 SP Install

Download the Shibboleth SP install from http://shibboleth.internet2.edu/shib-v2.0.html

Navigate to the downloads directory

select shibboleth, cppsp : 2.1 (or the latest stable version as on the front page) : From here choose either Win32 or Win64 folder depending on your needs : Inside this you should find an msi which you need to download to the system.

Run the installer. The default install location will be \opt\shiboleth-sp\. Be aware that the installer will pick a non system drive to install to if it is detected, so you should check the install path.

NOTE: While you can change the default folder you are advised not to. If you must change the folder do not put any spaces in the path name.

Basic Installer Outline

• Installs the shib daemon
• Set listening port - default 1600
• Install the ISAPI filter and configure the .sso shibolleth file extention for IIS

Manual Config/Install Check

While the installer usually works it has been known to not complete stages correctly, particularly in IIS7. To check the install or perform the install manually with the extracted files use the following as a guide.

All configuration is done in IIS Manager

To Add the filter

Right click the computer icon

Select ISAPI filters

Add a new filter called shibboleth and specify lib\Shibboleth\isapi_shib.dll

Map the .sso file extension (This is so virtual URLS can be specified to invoke the extension handler for each web site)

• Select the computer icon
• Select handler mappings
• Look for *.sso in the path column
• To add the extention mapping select Add script map and set the following:
  • Request Path = *.sso
  • Executable = isapi_shib.dll
  • Name = something sensible as defined by you

Add the Shibboleth ISAPI extension to the list of permitted extensions in the list of allowed extensions

Select the computer icon in IIS manager You should see

• Desc = Shibboleth Web Service Extension
• Restriction = Allowed
• Path = \opt\Shibboleth-sp\lib\shibboleth\isapi_shib.dll

If this is not there click Add in the right pane in IIS manager and

• Browse to set the path
• Add a description
• Put a tick in the box to allow

Permissions Issues with Manual Install

If you do a manual install then you will probably need to change the permissions on your install directory for IIS to work. IIS may run with different accounts and wrong permissions will cause various failures.

The IIS server process/s needs read access to most of the Shibboleth installation, except the shibboleth private key files. It will also need write access to \var\log\shibboleth to create the native.log file

Re-start IIS

NOTE:' Whenever you make a configuration change, either in the shibboleth2.xml and or in IIS you should re-start both services to make sure that changes are affected immediatly.

Shibboleth Configuration

1. Copy the Ucam Federation IDP metadata from: https://wiki.csx.cam.ac.uk/raven/'Ucam_Federation'_IdP_metadata

From the Raven wiki you should download the following two xml internal use skeleton files

1. Shibboleth2.xml: https://wiki.csx.cam.ac.uk/raven/Shibbileth2.xml_-_internal_use_skeleton

1. attribute-map.xml: https://wiki.csx.cam.ac.uk/raven/Attribute-map.xml_-_internal_use_skeleton

Backup Shibboleth2.xml and attribute-map.xml in \opt\shibboleth-sp\etc\shibboelth\ and create these files again from the skeleton files above.

All of the configuration is done in Shibboleth2.xml The basic areas you need to adjust from the template are listed below and can be found by searching for FIX-ME and apply the necessary edits described in the files comments and from the information here.

• ISAPI definition - Define the site and host for the ISAPI filter
• Port listener - The port that shibd will listen on
• Request mapper information - what to protect and who to give access to
• Application Defaults - what web sites to protect and remote user information to get

ISAPI definition

You need to specify the site ID and the name of the web site, ostensibly this will be the host name or the www reference for the site.

The site identifier default is 1. This can be found for a site by selecting the site folder in the left pane of IIS manager and looking at the ID column in the middle pane

Listener

Uncomment the second listener for Windows, the default port of 1600 should be used normally

Request Mapper

The default setting is to define a folder called /secure as being protected. Put you hosts name where FIX-ME is and change the folder if you want to protect a different named folder. Additional instructions for configurations (such as for just the site as a whole or to restrict for eppn, cn or other attribute can be found HERE

Application defaults

Set the entityID and the homeURL as per the comments

Checking and Running Shibboleth

Once you have edited the Shibboleth2.xml file you will need to re-load the Shibd service which parses the XML configuration file. If the service fails to restart you can use shibd.exe with the -check switch from a command shell to trouble shoot the XML. This will return a line number where there was a problem.

Navigate to \opt\Shibbolleth-sp\sbin\

Run shibd -check

This will return an line error where the parsing of the xml failed. Navigate to this (Ctrl+G in notepad) in Shibboleth2.xml and trouble shoot. Keep running shidb -check until the file is cleared and loaded correctly.

Re-start the Shibboleth service.

Re-start IIS