Deploy Shibboleth Target 1.2.1 on IIS Web Server
Author: Patrik Schnellmann <schnellmann@switch.ch> - SWITCH
$Date: 2005/04/22 15:40:44 $
$Revision: 1.4 $
Introduction
This document shows you how to set up a Shibboleth 1.2 target within the SWITCHaai Federation on a Windows 2003 Server with IIS 6.0. It complements the "Shibboleth Target Deployment Guide" of Internet2. Even though this guide does not specifically refer to IIS 4 and 5, it will also help to get Shibboleth working on these versions, too.
Note: For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the Deployment section of our website.
Original Deployment Documentation
To configure your resource within another federation or for another platform either check our website or refer directly to the original Shibboleth Target Deployment Guide.
Before you start...
..., please make sure you have the following things ready:
- A DNS entry for your Shibboleth target (Resource) as you will need the Fully Qualified Domain Name (FQDN) for a working configuration within the Federation
- IIS Web Server installed
- The Shibboleth 1.2.1a installer package for win32 shibboleth-1.2.1a-win.32.exe [asc] from Internet2 (stored locally)
- The SWITCHaai configuration files package
- Be aware that you will have to request a SWITCHpki server certificate (see: www.switch.ch/pki)
Installation
Installation process of Shibboleth 1.2
- Use default destination folder: c:\opt\shibboleth\
- Use the default value for "Shar Port Information": 1600
- Install Shar as service
Note: In the following, we assume you have installed Shibboleth in its default location. If you have not, you will have to adapt the configuration file accordingly.
When you are done with the installation program
- The Shibboleth files are c:\opt\shibboleth
- The SHAR is installed as a service, by default with the service name "SHAR_Default"
- The Path=%Path%;C:\opt\shibboleth\lib is set by the installer
- The server needs to be restarted.
Note: It may help to set Path=%Path%;C:\opt\shibboleth\bin to ease the use of (command line) tools provided by installer package (such as openssl.exe).
Configuration
Configuration of IIS Web Server
- Configure IIS as described in Shibboleth Target Deployment Guide, section 3.d. "Configure Microsoft IIS". Some additional remarks
- In IIS 6.0, there does not have to be an sspifilt entry in the ISAPI Filter list.
- Make sure that the setting "Verify that file exists" for the ISAPI Filter (isapi_shib) is not checked.
- The filter status should turn green when you make any request to the Web Server.
- For the example path that gets protected via shibboleth.xml, create a directory secure in your web root.
Note: The Shibboleth.shire file is just a dummy, but it's necessary if the IIS option "Verify that file exists" is set for the mapping to isapi_shib.dll.
Shibboleth Target Configuration
Extract the SWITCHaai configuration files from shibboleth-1.2-switchaai.zip and put them into C:\opt\shibboleth\etc\shibboleth\. Use the provided shibboleth.switchaai.xml as your shibboleth.xml configuration file.
Note: As you will have to replace {HOSTNAME} several times with your FQDN, using search/replace within your editor may save you some time.
The relevant modifications in shibboleth.xml are:
In ShibbolethTargetConfig/SHIRE/RequestMapProvider
In the RequestMap/Host elements, set the {HOSTNAME} and define directories that need to be protected by Shibboleth (i.e. needing a session).
In the Implementation/ISAPI/Site element, set the name attribute to reflect your FQDN (name="{HOSTNAME}").
Applications
In the Applications Element, set the attributes: id="default" providerId="urn:mace:switch.ch:SWITCHaai:pilot:{HOSTNAME}"
Sessions
In the Sessions Element, set the attributes: wayfURL="https://wayf1.switch.ch/SWITCHaai/WAYF" shireURL="/secure/Shibboleth.shire"
Errors
In the Errors Element, set the attribute: supportContact="{YOUR_EMAIL}" and customize the error pages, logo and css-stylesheet.
CredentialUse
(this SWITCHaai specific configuration setting is already provided with the shibboleth.switchaai.xml file)
TLS="SWITCHpki" Signing="SWITCHpki"
AAPProvider
(this SWITCHaai specific configuration setting is already provided with the shibboleth.switchaai.xml file)
Attribute uri="C:/opt/shibboleth/etc/shibboleth/AAP.switchaai.xml"
FederationProvider
(this SWITCHaai specific configuration setting is already provided with the shibboleth.switchaai.xml file)
Attribute uri="C:/opt/shibboleth/etc/shibboleth/sites.switchaai.xml"
TrustProvider
(this SWITCHaai specific configuration setting is already provided with the shibboleth.switchaai.xml file)
Attribute uri="C:/opt/shibboleth/etc/shibboleth/trust.switchaai.xml"
<saml:Audience>
(this SWITCHaai specific configuration setting is already provided with the shibboleth.switchaai.xml file)
urn:mace:switch.ch:SWITCHaai:pilot
CredentialsProvider/Credentials/FileResolver
(this SWITCHaai specific configuration setting is already provided with the shibboleth.switchaai.xml file)
Attribute Id="SWITCHpki"
Key
In the Key element, set <Path>C:/opt/shibboleth/etc/shibboleth/{HOSTNAME}.key</Path>
Certificate
In the Certificate element, set <Path>C:/opt/shibboleth/etc/shibboleth/{HOSTNAME}.crt</Path>
Enabling SSL
If not already done, request a SWITCHpki certificate for your Web Server. The same certificate can be used for both IIS and Shibboleth.
IIS Web Server
Request the SWITCHpki certificate
See "How to Obtain a SWITCHpki Server Certificate", Step 1 - Step 5 about how to proceed in general. The following instructions apply specifically to the IIS Web Server.
In IIS, the certificate requests can be done via the "Web Server Certificate Wizard".
- In IIS Manager, under the Web Sites folder, open the Properties for the site you want to create a request.
- Go to the Directory Security tab, under Secure communications, click Server Certificate.
- The Wizard gets started and allows you to Create a new certificate.
- At the end of the process you should have the certificate request file (C:\certreq.txt by default) saved. This file can be used to obtain the SWITCHpki certificate.
Import the server certificate in IIS
After you have got your SWITCHpki certificate, it's time to import it into IIS Web Server. This can be done similarly to the certificate request using the "Web Server Certificate Wizard".
Import the root certificates for SWITCHaai
Import the SWITCHpki certificate chain in IIS using the "Certificate Trust List Wizard".
- In IIS Manager, under the Web Sites folder, open the Properties for the site you want to create a request.
- Go to the Directory Security tab, under Secure communications, click New.
- The Wizard gets started and allows you to manage your certificate trust list (Add from Store / Add from File).
- Import the file with the Certification Authorities in the SWITCHaai Federation (ca-bundle.switchaai.crt).
Export the server certificate of IIS
This step may not be necessary if you already have your private key in a file, which can be the case if you generated your certificate request outside the IIS Web Server (i.e. with OpenSSL).
The SWITCHpki certificate installed on the IIS Web Server can be exported in order to be used with Shibboleth.
- In the MMC, use the Snap-In "Certificates". (You may have to install it before.)
- Select "Certificates (Local Computer)", Personal / Certificates. With right-click on the certificate get the context menu and choose "All Tasks / Export".
- Export the certificate into a .pfx-File without deleting the private key.
Shibboleth
- Extract the private key from the .pfx-File using openssl.exe:
$ openssl pkcs12 -in HOSTNAME.pfx -nocerts -nodes -out HOSTNAME.key
- Copy key and the certificate to the place as configured in shibboleth.xml:
C:\opt\shibboleth\etc\shibboleth\{HOSTNAME}.key
C:\opt\shibboleth\etc\shibboleth\{HOSTNAME}.crt
Note: For command line options of openssl, see http://www.openssl.org/