Guides: Debian GNU/Linux 6.0 from sources Windows with IIS Solaris from sources  
  
URL: https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.4/sp/deployment/windows-iis.html
Author: Lukas Hämmerle - SWITCH
$Date: 2012-07-30 11:07:13 +0200 (Mo, 30 Jul 2012) $
$Revision: 1858 $

Deployment of Shibboleth Service Provider (SP) 2.4.3 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 and configuration of a Shibboleth Sevice Provider (SP) 2.4.3 on a Windows with IIS system.
It covers the installation of the Shibboleth web server module as well as the Shibboleth daemon and their configuration for the SWITCHaai or AAI Test federation.

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

Assumptions

Please ensure that the following prerequisites are met before proceeding with the installation of the Shibboleth Service Provider:
X.509 certificate
A valid certificate is required for decrypting SAML assertions and/or establishing SSL connections to Identity Providers.
Please refer to http://www.switch.ch/aai/certificates/ for further information about certificates and certificate requirements.
The same certificate can be used by the web server and by the Shibboleth Service Provider. However, it is recommended that Shibboleth uses a self-signed certificate whereas the web server should use a certificate from a well-known CA.
Please follow the steps described below to create a self-signed certificate for between the Shibboleth components. See SWITCHaai Certificate Acceptance Policy.

Known issues

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

1. Setup Profile

In order make configuration easier and more convenient we kindly ask you to provide some information about your environment. This allows aut-generating and custom-tailoring some of the configuration files.

In which federation would you like to deploy your SP?
FQDN of the service?
Please provide the entityID (unique identifier) of the Service Provider:
Note The convention is to pick an entityID of the form https://#service host name#/shibboleth. 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.
Filesystem path to the configuration directory:
Note The location of the custom configuration should be separated in the C:\opt\shibboleth-sp\etc\shibboleth\ directory. It allows upgrading the Shibboleth Service Provider software without overwriting the existing configuration.
Filesystem path to the X.509 key:
Filesystem path to the X.509 certificate:
Filesystem path to the logging directory:
URL of the resource?
Support contact email address of the resource (will be shown in error Shibboleth messages):

1.1 Quick download of configuration files

If you are in a hurry and know the whole setup process, you can download all relevant configuration files directly 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.4.3, use the post-install archive:
http://shibboleth.net/downloads/service-provider/2.4.3/win32/shibboleth-sp-2.4.3-win32-postinstall.zip or
http://shibboleth.net/downloads/service-provider/2.4.3/win64/shibboleth-sp-2.4.3-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.net/downloads/service-provider/2.4.3/win32/shibboleth-sp-2.4.3-win32.msi or
http://shibboleth.net/downloads/service-provider/2.4.3/win64/shibboleth-sp-2.4.3-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/Metadata. This URL should return the dynamically generated XML metadata of this Service Provider.

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 certain requirements. Using the command below will respect all those requirements.

For creating a self signed certificate follow these steps: 

cd C:\opt\shibboleth-sp\etc\shibboleth\    
 $SHIB_HOME/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: 

...
log4j.appender.native_log.fileName=C:\opt\shibboleth-sp\var\log\shibboleth\native.log
...
log4j.appender.warn_log.fileName=C:\opt\shibboleth-sp\var\log\shibboleth\native_warn.log
...

The Shibboleth daemon log (shibd.log) and the transaction log (transaction.log) are configured in the file C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger: 

...
log4j.appender.shibd_log.fileName=C:\opt\shibboleth-sp\var\log\shibboleth\shibd.log
...
log4j.appender.warn_log.fileName=C:\opt\shibboleth-sp\var\log\shibboleth\shibd_warn.log
...
log4j.appender.tran_log.fileName=C:\opt\shibboleth-sp\var\log\shibboleth\transaction.log
...
log4j.appender.sig_log.fileName=C:\opt\shibboleth-sp\var\log\shibboleth\signature.log
...

4.3 Shibboleth service provider

The main configuration of the Shibboleth Service Provider is done in C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml: 
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    clockSkew="180">

    <!--
    By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache
    are used. See example-shibboleth2.xml for samples of explicitly configuring them.
    -->

    <!-- The OutOfProcess section contains properties affecting the shibd daemon. -->
    <OutOfProcess logger="C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger"/>

    <!--
    The InProcess section contains settings affecting web server modules.
    Required for IIS, but can be removed when using other web servers.
    -->
    <InProcess logger="C:\opt\shibboleth-sp\etc\shibboleth\native.logger">
        <ISAPI normalizeRequest="true" safeHeaderNames="true">
            <!--
            Maps IIS Instance ID values to the host scheme/name/port. The name is
            required so that the proper <Host> in the request map above is found without
            having to cover every possible DNS/IP combination the user might enter.
            -->
            <Site id="1" name="sp.example.org"/>
            <!--
            When the port and scheme are omitted, the HTTP request's port and scheme are used.
            If these are wrong because of virtualization, they can be explicitly set here to
            ensure proper redirect generation.
            -->
            <!--
            <Site id="42" name="virtual.example.org" scheme="https" port="443"/>
            -->
        </ISAPI>
    </InProcess>

    <!--
    To customize behavior for specific resources on Apache, and to link vhosts or
    resources to ApplicationOverride settings below, use web server options/commands.
    See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfigurationElements for help.
    
    For more examples of the RequestMap XML syntax instead, see the example-shibboleth2.xml
    file, and the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo topic.
    -->
    <RequestMapper type="Native">
        <RequestMap applicationId="default">
            <!--
            The example below requires a session for documents in /secure on the containing host with http and
            https on the default ports. Note that the name and port in the <Host> elements MUST match
            Apache's ServerName and Port directives or the IIS Site name in the <ISAPI> element
            below.
            -->
            <Host name="sp.example.org">
                <Path name="secure" authType="shibboleth" requireSession="true"/>
            </Host>
        </RequestMap>
    </RequestMapper>

    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
    <ApplicationDefaults entityID="https://sp.example.org/shibboleth"
                         homeURL="https://sp.example.org/"
                         REMOTE_USER="uniqueID persistent-id targeted-id"
                         signing="back" requireTransportAuth="false">

        <!--
        Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
        You MUST supply an effectively unique handlerURL value for each of your applications.
        The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
        a relative value based on the virtual host. Using handlerSSL="true", the default, will force
        the protocol to be https. You should also add a cookieProps setting of "; path=/; secure"
        in that case. Note that while we default checkAddress to "false", this has a negative
        impact on the security of the SP. Stealing cookies/sessions is much easier with this disabled.
        -->
        <Sessions lifetime="28800" timeout="3600" 
            checkAddress="false" consistentAddress="true"
            relayState="ss:mem" handlerSSL="true"
            cookieProps="; path=/; secure; HttpOnly">

            <!--
            In order to use a default Identity Provider add an attribute like:
            entityID="https://idp.example.org/shibboleth"
            to the SSO element. It's value should be the entityID of the
            default Identity Provider. 
            -->
            <SSO discoveryProtocol="SAMLDS" discoveryURL="https://wayf.switch.ch/SWITCHaai/WAYF">
              SAML2 SAML1
            </SSO>

            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>

            <!--
            In addition to the standard SessionInitiator it is also possible
            to define custom SessionInitiators to enforce specific settings.
            More information is available at:
            https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessionInitiator
            -->

            <!--
            <SessionInitiator type="Chaining" Location="/DS" id="DS" relayState="cookie" isDefault="true">
                <SessionInitiator type="SAML2" acsByIndex="false" acsIndex="1" template="bindingTemplate.html" />
                <SessionInitiator type="Shib1" acsIndex="5"/>
                <SessionInitiator type="SAMLDS" URL="https://wayf.switch.ch/SWITCHaai/WAYF"/>
            </SessionInitiator>
            -->            
            
            <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
            <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>

            <!-- Status reporting service. -->
            
            <!-- 
            Please note that the IP 130.59.138.32 is used by the AAI Resource Registry. 
            By allowing the Resource Registry to periodically access the status handler, 
            it is possible to monitor this Service Provider and to specifically alert 
            administrators in case of configuration or security relevant issues.
            If you feel uncomfortable with this, set acl="127.0.0.1"
            -->
            <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1 130.59.138.32"/>

            <!-- Session diagnostic service. -->
            <Handler type="Session" Location="/Session" showAttributeValues="false"/>

            <!-- JSON feed of discovery information. -->
            <!--
            <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
            -->
        </Sessions>

        <!--
        Allows overriding of error template information/filenames. You can
        also add attributes with values that can be plugged into the templates.
        -->
        <Errors supportContact="aai@example.org"
            logoLocation="https://www.switch.ch/aai/design/images/SWITCHaai.gif"
            styleSheet="https://www.switch.ch/aai/design/shib-error.css"/>
        
        <!-- Example of locally maintained metadata. -->
        <!--
        <MetadataProvider type="XML" file="partner-metadata.xml"/>
        -->
        
        <MetadataProvider type="XML" validate="true"
            uri="http://metadata.aai.switch.ch/metadata.switchaai.xml"
            backingFilePath="C:\opt\shibboleth-sp\etc\shibboleth\metadata.switchaai.xml"
            reloadInterval="3600">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="604800"/>
            <MetadataFilter type="Signature" verifyName="false">
                <TrustEngine type="StaticPKIX"
                    certificate="C:\opt\shibboleth-sp\etc\shibboleth\SWITCHaaiRootCA.crt.pem"
                    verifyDepth="2" checkRevocation="fullChain"/>
            </MetadataFilter>
        </MetadataProvider>

        <!-- Map to extract attributes from SAML assertions. -->
        <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="C:\opt\shibboleth-sp\etc\shibboleth\attribute-map.xml"/>
        
        <!-- Use a SAML query if no attributes are supplied during SSO. -->
        <AttributeResolver type="Query" subjectMatch="false"/>

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" validate="true" reloadChanges="false" path="C:\opt\shibboleth-sp\etc\shibboleth\attribute-policy.xml"/>

        <!-- Simple file-based resolver for using a single keypair. -->
        <CredentialResolver type="File" key="C:\opt\shibboleth-sp\etc\shibboleth\sp-key.pem" certificate="C:\opt\shibboleth-sp\etc\shibboleth\sp-cert.pem"/>

        <!--
        The default settings can be overridden by creating ApplicationOverride elements (see
        the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApplicationOverride topic).
        Resource requests are mapped by web server commands, or the RequestMapper, to an
        applicationId setting.
        
        Example of a second application (for a second vhost) that has a different entityID.
        Resources on the vhost would map to an applicationId of "admin":
        -->
        <!--
        <ApplicationOverride id="admin" entityID="https://admin.example.org/shibboleth"/>
        -->
    </ApplicationDefaults>
    
    <!-- Policies that determine how to process and authenticate runtime messages. -->
    <SecurityPolicyProvider type="XML" validate="true" reloadChanges="false" path="C:\opt\shibboleth-sp\etc\shibboleth\security-policy.xml"/>

    <!-- Low-level configuration about protocols and bindings available for use. -->
    <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="C:\opt\shibboleth-sp\etc\shibboleth\protocols.xml"/>

</SPConfig>
Note Please verify that the site id within InProcess corresponds to the instance ID of the IIS configuration. Further information can be found on https://wiki.shibboleth.net/confluence/display/SHIB/InstanceID.

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

Warning Before updating the Service Provider, it is strongly recommended to first backup the C:\opt\shibboleth-sp\etc\shibboleth\attribute-map.xml!

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

Warning Before updating the Service Provider it is strongly recommended to first backup the C:\opt\shibboleth-sp\etc\shibboleth\attribute-policy.xml!

4.4 Download federation specific file

Download the trust anchor certificate to verify metadata signatures 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.exe 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

According to the convention, the entityID should have the form of a URL. If the entityID is used as a URL (https://sp.example.org/shibboleth), this URL should return an entity's metadata. In order for this to work, the web server must be configured accordingly.

In IIS it is possible to create a folder shibboleth with the following properties: (Credits to Mathias Rufer from UNINE)
IIS redirect Make sure to set all the SSLCertificateFiles to the right ones.

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 the following message, everything is as expected: 
overall configuration is loadable, check console for non-fatal problems
If there are any ERROR messages it is strongly recommended to have a look at the problem. WARN messages are generally not very serious but it also is recommended to examine the problem.
Start the Shibboleth daemon: 
net start shibd_Default
Restart IIS: 
net stop W3SVC
net start W3SVC
Use the status URL https://sp.example.org/Shibboleth.sso/Metadata for a quick test. This URL should return the dynamically generated XML metadata of this Service Provider.

AAI Resource Registry

In order to activate the Service Provider within the federation it is necessary to register it with the Resource Registry. After this procedure, the metadata of this Service Provider will be included in the federation metadata. Therefore, all AAI components will learn about this new Service Provider.
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) in order to generate federation metadata and various configuration files.

To register a Service Provider:
  1. Go to the AAI Resource Registry.
  2. Log in with a SWITCHaai or AAI Test account. Use 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.
    SWITCHaai accounts can also be used to manage AAI Test resources but not vice versa.
  3. Click on the tab Resources
  4. Click on Add a Resource Description
  5. Click on Run Shibboleth 2.x wizard
  6. Fill out all forms that are marked incomplete. Some forms do not need to be filled out completely.
  7. After completing all sections (they should all be marked as 'optional' or 'ok'), click on Submit for Approval.
    A Resource Registration Authority administrator of your organization then has to approve the Resource Description in order to make it active. Only after this step, its description will be included in federation metadata.

6. Troubleshooting

6.1 Logfiles

If some of the above tests are unsuccessful, we recommend the following procedure:

Note In order to avoid the log files to grow to enormous sizes, set the log level to an accurate level like WARN or INFO after debuging.

6.2 Common problems

Find below a list of common problems and possible solutions:
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 . If shibd is not run as root user, you might have to adapt the owner of the log directory and files to the user that runs shibd.
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 NativeSPTroubleshootingCommonErrors 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="https://www.switch.ch/aai/design/images/SWITCHaai.gif"
  styleSheet="https://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 1858 2012-07-30 09:07:13Z haemmer $