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 which contains all the elements required to run the Shibboleth module.
- Common files
- Internet Information Services Manager
- World Wide Web Service
IIS7:
IIS7 on Windows Server 2008 / Windows Vista 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)
IIS8/8.5:
IIS8/8.5 on Windows Server 2012/2012R2 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
(See also https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPWindowsInstall)
Download the Shibboleth SP install from http://shibboleth.net/downloads/service-provider/latest/
- 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 (leave this alone unless absolutely necessary)
- Install the ISAPI filter and configure the .sso shibolleth file extention for IIS
NOTE: The Installer will prompt for a system restart.
Manual Configuration & 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
IIS6
Web Services Extension
Select the Web Services Extentions folder. You should see an entry for:
- Shibboleth Web Services Extention - status Allowed
To add it manually you need to add \opt\Shibboleth-sp\lib\Shibboleth\isapi_shib.dll
ISAPI Filter
Right click the Web Sites folder in IIS manager Select ISAPI filters tab
You should see a green up arrow for a filter called Shibboleth with a priority of high.
Again this cab be added from the isapi_shib.dll found in \opt\Shibboleth-sp\lib\Shibboleth\
IIS7
To Add the filter
- Right click the computer icon
- Select ISAPI filters
- Add a new filter called shibboleth and specify \opt\Shibboleth-sp\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
IIS8/8.5
To Add the filter
- Select the computer icon in the left-hand panel
- Select ISAPI filters from the IIS section of the right-hand panel
- Add a new filter called shibboleth and specify C:\opt\shibboleth-sp\lib64\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 in the left-hand panel
- Select handler mappings from the IIS section of the right-hand panel
- Look for *.sso in the path column
- To add the extention mapping select Add script map and set the following:
- Request Path = *.sso
- Executable = C:\opt\shibboleth-sp\lib64\shibboleth\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 the left-hand panal Select ISAPI and CGI Restrictions from the IIS section of the right-hand panel You should see
- Desc = Shibboleth Web Service Extension
- Restriction = Allowed
- Path = C:\opt\shibboleth-sp\lib64\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
Copy XML Source & Skeleton Files
The Ucam Federation IDP meta data is automatically downloaded by the Shibboleth2.xml configuration file. The data is still available from here for reference.
- Ucam Federation IDP metadata from: https://wiki.csx.cam.ac.uk/raven/'Ucam_Federation'_IdP_metadata
You will need the following two xml internal use skeleton files, they are available from;
- 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.
Edit Shibboleth2.xml
The shibd service does an automatic re-load of the Shibboleth2.xml configuration file periodically but you are advised to restart the service whenever you make a configuration change, and IIS, to make sure that your changes are applied.
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 at Shibboleth_access_control_using_shibboleth2.xml.
Application defaults
Set the entityID and the homeURL as per the comments
Checking and Running Shibboleth2.xml
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.
At a command prompt navigate to \opt\Shibbolleth-sp\sbin\ and run the command
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
Registering your SP
Before you can proceed any further you will need to register you SP, at least with Raven. See SP registration for details.
Testing your SP
You should then access your host http://<hostname>/secure (or whatever folder you have selected to protect). You should be re-directed to Raven to authenticate. If you have content this will be displayed, if not you will just see a 404 error - but the re-direction and authentication should take place.
If no Raven re-direction happens you need to check the log files for information. The logs are found in \opt\Shibboleth-sp\var\log\shibboleth
- native.log
- shibd.log
- transaction.log
Attribute Check
Once someone has authenticated you can check what attributes you are recieving from the IDP.
In the browser enter in http://<hostname>/Shibboleth.sso/Session
Which should display a page which contains something like:
Attributes ---------- affiliation: member@cam.ac.uk;member@eresources.lib.cam.ac.uk entitlement: urn:mace:dir:entitlement:common-lib-terms eppn: jw35@cam.ac.uk targeted-id: MlWd0XIR7juZvwvarOVdYiUWPW0=@cam.ac.uk
and probably other things.
Other Considerations
The instructions here will allow you to have a basic IIS web site protecting a folder of /secure (or something else if you have chosen to make a change). You can create more complicated access control, e.g. limiting access by eppn or other attribute. You can increase the scope of who you can authenticate (SP registration) and there are some security and SSL options you might want to do.
