Guides: Debian GNU/Linux 5.0 with backports packages Debian GNU/Linux 5.0 from sources Linux with RPM packages Windows with IIS Solaris from sources Mac OS X with MacPorts  
  
URL: https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.3/sp/deployment/windows-iis.html
Author: Halm Reusser - SWITCH
$Date: 2010-12-22 11:06:13 +0100 (Mi, 22 Dez 2010) $
$Revision: 1106 $

Deployment of Shibboleth Service Provider (SP) 2.3.1 on
Windows with IIS

Table of contents

0. Introduction

Note For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the deployment section of the SWITCHaai website.

This guide describes the installation & configuration of a Shibboleth Sevice Provider (SP) 2.3.1 on a Windows with IIS. It covers the installation of the Shibboleth Webserver authentication module as well as the Shibboleth daemon and its configuration for the SWITCHaai federation.

For further information about Shibboleth Sevice Provider, take a look at the references.

Assumption

Before starting to install Shibboleth Sevice Provider, assure that the following prerequisites are met:
A proper certificate
For decrypting the assertions and/or provide an SSL connection to the resource, a certificate is required.
Please refer to http://www.switch.ch/aai/certificates/ for further information about certificates.
You can use the same certificate for the SSL webserver connection and for Shibboleth Service Provider.
It is also possible to create a self-signed certificate for communciation usage between the Shibboleth components.
If you need that opportunity, please follow the steps described below.

Known issues

Follwing issues are known and should be take into account when installing a Shibboleth Service Provider:
libcurl SSL/TLS support
Please be aware that the Shibboleth Service Provider requires that the libcurl library is linked against openssl and not gnutls.

1. Setup Profile

For convenience, you may decide to dynamically profile your setup by providing some information about your environment in the this step.

In which federation you will deploy your SP?
What is the FQDN of your service?
Define an unique identifier of your Service Provider, called entityID:
Note In cases where the service host name (e.g. elearning.example.org) is different from the system name (e.g. web-host27.example.org), one should always use the service hostname for URLs and the Service Provider's entityID.
Where should your Shibboleth configuration directory be?
Note The location of your custom configuration should be separated in the C:\opt\shibboleth-sp\etc\shibboleth\ directory. It allows you to upgrade the Shibboleth Service Provider software without overwriting your existing configuration. When migrating from a Shibboleth Service Provider 1.x to 2.x, this way the two configurations are kept separate from each other.
Where is your X509 key located?
Where is your X509 certificate located?
What is your log directory?
What is the home URL of your resource?
What is the support contact of your resource?

1.1 Quick download configuration files

If you are in a hurry and know the whole setup process, you can download all relevant configuration files here:

2. Prerequisites

Before starting to build and configure the Shibboleth Sevice Provider, assure that the following prerequisites are met:
IIS 6
The server has to be configured as a Web Server by selecting the "Internet Information Service (IIS)" option
in the Windows Component selection tool.
Assure that IIS 6 is properly configured and working.
Service Packs
It is strongly recommended to have an up-to-date system before starting the installation.
NTP
The Windows Time service (w32time) has to be activated and well configured. Servers running Shibboleth
should have their system time synchronized in order to avoid clock-skews.

3. Installation

Note Here is a list of some useful Windows management consoles, which can be opened by 'Start -> Run':
IIS Management Console
%SYSTEMROOT%\System32\inetsrv\iis.msc
Event viewer
%SYSTEMROOT%\System32\eventvwr.msc
Local User & Group Management
%SYSTEMROOT%\System32\lusrmgr.msc
Services
%SYSTEMROOT%\System32\services.msc

Post-installation updates

Warning If you already have a working Shibboleth 2.x installation, you should do an upgrade by the post installation to keep your running configuration.

To update, e.g. Shibboleth 2.0 to 2.3.1, use the post-install archive:
http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/2.3.1/win32/shibboleth-sp-2.3.1-win32-postinstall.zip or
http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/2.3.1/win64/shibboleth-sp-2.3.1-win64-postinstall.zip
Services (IIS and Shibboleth) will have to be stopped before the update and started afterwards.

3.1 Service Provider Installation

First of all, download the latest Shibboleth .msi package from Internet2:
http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/2.3.1/win32/shibboleth-sp-2.3.1-win32.msi or
http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/2.3.1/win64/shibboleth-sp-2.3.1-win64.msi

Note It is recommended that you install the software to C:\opt\shibboleth-sp\ if possible.

You might want to install the Shibboleth SP under a different path than the proposed one, which we do not suggest. But still: if you decide to install the Shibboleth SP under a path containing spaces like e.g. "C:\Program Files", use path names according to the 8.3 convention (e.g. "C:\Progra~1") as the installer does not properly escape the path names when installing the shibd service.

  1. Run the installer
  2. Read and accpet the license agreement
  3. Choose C:\opt\shibboleth-sp\ as destination folder
  4. Check 'Install Shibd daemon' and choose 1600 as port number
  5. Check 'Install ISAPI module' and choose .sso as file extension
  6. Finish the installation
  7. Restart your computer

3.2 Webserver Configuration

After rebooting, IIS should be configured for basic support (if you asked it to do so).
If you have problems, need to manually configure it or want to verify what happened, the IIS steps are described here.

For an instant test, if the Shibboleth deamon and ISAPI Filter are working access with your browser to https://localhost/Shibboleth.sso/Status.
If you get an XML document it is fine.

3.3 Prepare Logging

Check C:\opt\shibboleth-sp\var\log\shibboleth\, if the logfiles are created. If not check the permissions.

Note Esnure that native.log is writable by the IIS process.
Further information can be found here

4. Configuration

4.1 Self-signed certificate generation

Note You can skip this if you are going to use a certificate from a well known CA or if you already created a self signed certificate in a previous installation.
Note Please consider that a self-signed certificate has to fulfil some requirements. Using the command below will respect those requirements.

For creating a self signed certificate follow these steps: 

cd C:\opt\shibboleth-sp\etc\shibboleth\    
 C:\opt\shibboleth-sp\etc\shibboleth\keygen.bat -h sp.example.org -y 3 -e https://sp.example.org/shibboleth

4.2 Logging

The Shibboleth Apache module log is configured by C:\opt\shibboleth-sp\etc\shibboleth\native.logger
The Shibboleth daemon and the transaction log are configured by C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger

4.3 Shibboleth service provider

The main configuration of the Shibboleth Service Provider is done in C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml:
Note Please verify the site id within InProcess due to the IIS instance ID of your configuration. Further information can be found at https://wiki.shibboleth.net/confluence/display/SHIB/InstanceID.

Download attribute-map.xml to your C:\opt\shibboleth-sp\etc\shibboleth\ directory.

Warning In case of an update, you should backup your C:\opt\shibboleth-sp\etc\shibboleth\attribute-map.xml first!

Download attribute-policy.xml to your C:\opt\shibboleth-sp\etc\shibboleth\ directory.

Warning In case of an update, you should backup your C:\opt\shibboleth-sp\etc\shibboleth\attribute-policy.xml first!

4.4 Download federation specific file

Donwload the trust anchor of the metadata signature from http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem
to C:\opt\shibboleth-sp\etc\shibboleth\.

Compare the certificate fingerprint with the fingerprint of the SWITCHaai Root CA certificate shown on https://www.switch.ch/pki/aai/: 

openssl x509 -in C:\opt\shibboleth-sp\etc\shibboleth\SWITCHaaiRootCA.crt.pem -fingerprint -sha1 -noout
SHA1 Fingerprint=3C:E2:5A:E0:9D:B4:BB:2B:FD:33:3C:22:80:39:F7:FC:4A:F9:2C:E9

4.5 Enable metadata access at entityID URL

It is recommened to enable at the entityID URL (https://sp.example.org/shibboleth) access to the metadata of the Service Provider.

In IIS it is possible to create a folder shibboleth with the following properties: (Credits to Mathias Rufer from UNINE)
IIS redirect

5. Run & Test

Test the configuration file: 
C:\opt\shibboleth-sp\sbin\shibd.exe -check -config C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml
Note If the output is only one line containing this: 
overall configuration is loadable, check console for non-fatal problems
It is alright.
Start the Shibboleth daemon: 
net start shibd_Default
Restart IIS: 
net stop W3SVC
net start W3SVC
For testing purposes, there is the status URL https://sp.example.org/Shibboleth.sso/Status, which returns information about the setup as an XML response.
For accessing the status URL, the accessing host has to be enabled in C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml: 
...
<!-- Status reporting service. -->
<Handler type="Status" Location="/Status" acl="127.0.0.1"/>
...
Warning If the acl attribute is removed, anyone is permited to access the status handler. Please consider, that the status handler can return some potentially sensitive information about your configuration.

AAI Resource Registry

In order to activate your Service Provider within the federation you need to register it with the Resource Registry.
The purpose of the Resource Registry is to have an up-to date list of all Identity Providers and Service Providers in the SWITCHaai Federation.
(See the information about the Resource Registry).

To register a resource:
  1. Go to the AAI Resource Registry.
  2. Log in via SWITCHaai|AAITest. Use your organisation account to get access. In case your organisation doesn't operate yet an AAI Identity Provider, please ask aai@switch.ch for an account.
  3. Click on the tab Resource Administration
  4. Click on Add a Resource Description
  5. Click on Run Shibboleth 2.x assistant
  6. Fill out all forms that are marked incomplete. Some forms do not need to be filled out completely.
  7. After you have completed all sections (they should all be marked as 'optional' or 'ok'), click on Submit for Approval.
    A Resource Registration Authority administrator then has to approve the Resource Description in order to make it active.

6. Troubleshooting

6.1 Logfiles

If some of the above tests are not successful, we recommend to do the following:

Note To avoid a blow up of the logfiles, set the log level after debuging to an accurate level like WARN or INFO.

6.2 Common problems

Following is a list of common problems that you may check:
No log files are written
Check the permissions of the log files or the path for the log files set in C:\opt\shibboleth-sp\etc\shibboleth\native.logger or C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger .
No attributes/Certificates problems
Check the Apache SSL certificate with the https://tools.switch.ch/certchaintest/ to make sure the full certificate chain up to the root CA certificate is attached to your certificate.

In case you don't understand or don't find the cause of the error, have a look at the Internet2 Shibboleth SP 2.x - Common Errors web page.

7. Productionalization

Some good practices according Service Provider productionalization:

BEST CURRENT PRACTICES for operating a SWITCHaai Service Provider
The document describes best current practices for operating a Service Provider (SP) within the SWITCHaai federation in production use. It is meant to cover service management and operational related aspects as well as the technical infrastructure for successfully operating an SP.
Subscribe to the SWITCHaai mailing lists
Important information about the SWITCHaai federation are distributed by the AAI-Operations mailing list. Therefore the administrator of the Service Provider should subscribe to the list.
News and announcements are sent by the AAI-Announce mailing list. You might subscribe to it as well.
Customizing error pages
The error pages and messages can be configured in C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml: 
<Errors
  session="sessionError.html"
  metadata="metadataError.html"
  access="accessError.html"
  ssl="sslError.html"
  localLogout="localLogout.html"
  globalLogout="globalLogout.html"
  supportContact="aai@example.org"
  logoLocation="http://www.switch.ch/aai/design/images/SWITCHaai.gif"
  styleSheet="http://www.switch.ch/aai/design/shib-error.css"/>
Adjust at minimum the logoLocation and styleSheet. You may want to fully customize the html pages.
Note See https://wiki.shibboleth.net/confluence/display/SHIB2/Productionalization, section Service Provider for more information.

8. References 

--
$Id: index.php 1106 2010-12-22 10:06:13Z reusser $