Installing SP2.x under Windows: Difference between revisions

From RavenWiki
Jump to navigationJump to search
No edit summary
 
(26 intermediate revisions by 4 users not shown)
Line 12: Line 12:
===IIS7:===
===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;
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
*Web Server IIS
Line 19: Line 19:
*IIS 6 Management compatibility (required to installed Shibolleth SP using the installer)  
*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==
==IIS Configuration==
Line 25: Line 32:
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.
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==


==Shibboleth2 SP Install==
(See also https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPWindowsInstall)


Download the Shibboleth SP install from http://shibboleth.internet2.edu/shib-v2.0.html
Download the Shibboleth SP install from http://shibboleth.net/downloads/service-provider/latest/


*Navigate to the downloads directory
* Choose either Win32 or Win64 folder depending on your needs  
*Select shibboleth
* Inside this you should find an msi which you need to download to the system.
*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.
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.
Line 43: Line 47:
===Basic Installer Outline===
===Basic Installer Outline===


*Installs the shib daemon
* Installs the shib daemon
*Set listening port - default 1600 (leave this alone unless absolutely necessary)
* Set listening port - default 1600 (leave this alone unless absolutely necessary)
*Install the ISAPI filter and configure the .sso shibolleth file extention for IIS
* 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 ===
===Manual Configuration & Install Check ===
Line 58: Line 64:


Select the Web Services Extentions folder.  You should see an entry for:
Select the Web Services Extentions folder.  You should see an entry for:
*Shibboleth Web Services Extention - status Allowed
* Shibboleth Web Services Extention - status Allowed


To addit manually you need to add \opt\Shibboleth-sp\lib\Shibboleth\isapi_shib.dll
To add it manually you need to add \opt\Shibboleth-sp\lib\Shibboleth\isapi_shib.dll


=====ISAPI Filter=====
=====ISAPI Filter=====
Line 70: Line 76:


Again this cab be added from the isapi_shib.dll found in \opt\Shibboleth-sp\lib\Shibboleth\
Again this cab be added from the isapi_shib.dll found in \opt\Shibboleth-sp\lib\Shibboleth\


====IIS7====
====IIS7====
Line 81: Line 86:
=====Map the .sso file extension (This is so virtual URLS can be specified to invoke the extension handler for each web site)=====
=====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 the computer icon
*Select handler mappings
* Select handler mappings
*Look for *.sso in the path column
* Look for *.sso in the path column
*To add the extention mapping select Add script map and set the following:
* To add the extention mapping select Add script map and set the following:
**Request Path = *.sso
** Request Path = *.sso
**Executable = isapi_shib.dll
** Executable = isapi_shib.dll
**Name = ''something sensible as defined by you''
** 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=====
=====Add the Shibboleth ISAPI extension to the list of permitted extensions in the list of allowed extensions=====


Select the computer icon in IIS manager
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
You should see
*Desc = Shibboleth Web Service Extension
* Desc = Shibboleth Web Service Extension
*Restriction = Allowed
* Restriction = Allowed
*Path = \opt\Shibboleth-sp\lib\shibboleth\isapi_shib.dll
* 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
If this is not there click Add in the right pane in IIS manager and


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


====Permissions Issues with Manual Install====
====Permissions Issues with Manual Install====
Line 119: Line 155:
The Ucam Federation IDP meta data is automatically downloaded by the Shibboleth2.xml configuration file.  The data is still available from here for reference.
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
* 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;
You will need the following two xml internal use skeleton files, they are available from;


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


* attribute-map.xml: https://wiki.csx.cam.ac.uk/raven/Attribute-map.xml_-_internal_use_skeleton
* attribute-map.xml: https://wiki.csx.cam.ac.uk/raven/Attribute-map.xml_-_internal_use_skeleton
Line 135: Line 171:
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.
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
* ISAPI definition - Define the site and host for the ISAPI filter
*Port listener - The port that shibd will listen on
* Port listener - The port that shibd will listen on
*Request mapper information - what to protect and who to give access to
* 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
* Application Defaults - what web sites to protect and remote user information to get


====ISAPI definition====
====ISAPI definition====
Line 152: Line 188:
====Request Mapper====
====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
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====
====Application defaults====
Line 162: Line 198:
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.   
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\ and run the command
At a command prompt navigate to \opt\Shibbolleth-sp\sbin\ and run the command
* shibd -check
  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.
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.
Line 171: Line 207:
Re-start IIS
Re-start IIS


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.
==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 <nowiki>http://<hostname>/secure</nowiki> (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
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
* native.log
*shibd.log
* shibd.log
*transaction.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 <nowiki>http://<hostname>/Shibboleth.sso/Session</nowiki>
 
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.
* [[Configuring Shibboleth access control|Configuring access control]]
* [[SSL, certificates and security with Shibboleth|Using SSL and certificates]]
* [[Virtual hosting issues with Shibboleth|Virtual hosting issues]]

Latest revision as of 15:38, 27 May 2015

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.

You will need the following two xml internal use skeleton files, they are available from;

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.