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/debian-lenny-source.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
Debian GNU/Linux 5.0 from sources

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 Debian GNU/Linux 5.0 from sources. 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 /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 installation directory?
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:
sudo
Allows to run commands as user with root privileges
Apache HTTP 2.2
sudo aptitude install apache2
For configuration, see at the Apache HTTP documentation in the references.
OpenSSL
For working with x509 certificates
sudo aptitude install openssl
NTP
Servers running Shibboleth must have their system time synchronized in order to avoid clock-skew errors:
sudo aptitude install ntp
Shibboleth build environment
Since the Shibboleth Service Provider is implemented in C/C++, some C/C++ build tools are needed:
sudo aptitude install gcc g++ make
The Shibboleth service provider is linked against some external libraries. The needed header files and libraries are:
sudo aptitude install libssl0.9.8 libssl-dev
sudo aptitude install libcurl3 libcurl3-dev
sudo aptitude install libxerces-c28 libxerces-c2-dev
sudo aptitude install libxml-security-c14 libxml-security-c-dev
sudo aptitude install apache2-threaded-dev

3. Installation

3.1 Source code download

Define and create the build directory: 
export MYBUILD=~/shibsp2.3.1-build
mkdir $MYBUILD
Download and extract the needed sources: 
wget http://shibboleth.internet2.edu/downloads/log4shib/latest/log4shib-1.0.4.tar.gz -P $MYBUILD
wget http://shibboleth.internet2.edu/downloads/opensaml/cpp/latest/xmltooling-1.3.3.tar.gz -P $MYBUILD
wget http://shibboleth.internet2.edu/downloads/opensaml/cpp/latest/opensaml-2.3.tar.gz -P $MYBUILD
wget http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/latest/shibboleth-sp-2.3.1.tar.gz -P $MYBUILD
Note http://shibboleth.internet2.edu/downloads/ is replicated at http://mirror.switch.ch/ftp/mirror/shibboleth/ 
for f in $MYBUILD/*.tar.gz; do tar -xzvf $f -C $MYBUILD; done

3.2 Build

Define some required environment variables. Just adjust SHIB_HOME if the target directory is somewhere else: 
export SHIB_HOME=/opt/shibboleth-sp-2.3.1/
Create the target directory: 
sudo mkdir $SHIB_HOME
1. Log4Shib: 
cd $MYBUILD/log4shib-1.0.4/
./configure --disable-static --disable-doxygen --prefix=$SHIB_HOME
make
sudo make install
2. XML-Tooling: 
cd $MYBUILD/xmltooling-1.3.3/
./configure --with-log4shib=$SHIB_HOME --prefix=$SHIB_HOME -C
make
sudo make install
3. OpenSAML: 
cd $MYBUILD/opensaml-2.3/
./configure --prefix=$SHIB_HOME --with-log4shib=$SHIB_HOME -C
make 
sudo make install
4. Shibboleth Service Provider: 
cd $MYBUILD/shibboleth-2.3.1/
./configure --with-saml=$SHIB_HOME --enable-apache-22 --with-log4shib=$SHIB_HOME --with-xmltooling=$SHIB_HOME --prefix=$SHIB_HOME -C
make
sudo make install

3.3 Define the current Shibboleth SP release

Note It is recommended to create a symlink /opt/shibboleth-sp2/, which points to the current Shibboleth Service Provider software release (e.g. /opt/shibboleth-sp-2.3.1/ Installing/updating it this way, prevents you to adjust all the path references in the configuration files each time and allows you smoothly upgrades between new software releases/patches.
Symlink the current installation: 
if [ -L /opt/shibboleth-sp2 ] ; then sudo rm /opt/shibboleth-sp2 ; fi;
sudo ln -sf $SHIB_HOME /opt/shibboleth-sp2

3.4 Install Shibboleth Apache module

Create the file /etc/apache2/mods-available/shib.load: 
# Load the shibboleth module

LoadModule mod_shib /opt/shibboleth-sp2/lib/shibboleth/mod_shib_22.so
Create the file /etc/apache2/mods-available/shib.conf: 
# Global Configuration
# This is the XML file that contains all the global, non-apache-specific
# configuration.  Look at this file for most of your configuration parameters.
ShibConfig /etc/shibboleth/shibboleth2.xml

# Used for example logo and style sheet in error templates.
<IfModule mod_alias.c>
  <Location /shibboleth-sp>
    Allow from all
  </Location>
  Alias /shibboleth-sp/main.css /opt/shibboleth-sp2/share/doc/shibboleth/main.css
  Alias /shibboleth-sp/logo.jpg /opt/shibboleth-sp2/share/doc/shibboleth/logo.jpg
</IfModule>
Adjust the Apache configuration /etc/apache2/envvars: 
...
...
# This file is generated from envvars-std.in
#

export LD_LIBRARY_PATH=/opt/shibboleth-sp2/lib
Enable the Shibboleth Apache module: 
sudo a2enmod shib

3.5 Install Shibboleth daemon

Copy the distribution init script: 
sudo cp $SHIB_HOME/etc/shibboleth/shibd-debian /etc/init.d/shibd
Adjust the init script: 
PATH=/sbin:/bin:/usr/sbin:/usr/bin
DESC="Shibboleth 2 daemon"
NAME=shibd
SHIB_HOME=/opt/shibboleth-sp2/
SHIBSP_CONFIG=/etc/shibboleth/shibboleth2.xml
LD_LIBRARY_PATH=$SHIB_HOME/lib
DAEMON=$SHIB_HOME/sbin/shibd
SCRIPTNAME=/etc/init.d/$NAME
PIDFILE=/var/run/$NAME.pid

...
Install the init script: 
sudo chmod +x /etc/init.d/shibd
sudo update-rc.d shibd defaults

3.6 Prepare your custom configuration

Warning This step is only needed if you do a fresh installation. In case of an update, these steps will overwrite the existing configuration files, which may not be what you want!
Copy some configuration files: 
sudo mkdir /etc/shibboleth/ 

sudo cp $SHIB_HOME/etc/shibboleth/native.logger /etc/shibboleth/ 
sudo cp $SHIB_HOME/etc/shibboleth/shibd.logger /etc/shibboleth/ 
sudo cp $SHIB_HOME/etc/shibboleth/syslog.logger /etc/shibboleth/

3.7 Prepare logging directory

Note This step is only needed if you do a fresh installation. In case of an update these steps where already done.
Note The Shibboleth Apache module log (/etc/shibboleth/native.logger) runs by the Apache process and has to be writeable.
Create logging directory and set according permissions: 
sudo mkdir -p /var/log/shibboleth/ 
sudo touch /var/log/shibboleth/shibd.log 
sudo touch /var/log/shibboleth/native.log 
sudo chgrp www-data /var/log/shibboleth/native.log 
sudo chmod g+w /var/log/shibboleth/native.log

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 /etc/shibboleth/    
sudo sh /opt/shibboleth-sp-2.3.1/etc/shibboleth/keygen.sh -h sp.example.org -y 3 -e https://sp.example.org/shibboleth

4.2 Logging

The Shibboleth Apache module log is configured by /etc/shibboleth/native.logger
The Shibboleth daemon and the transaction log are configured by /etc/shibboleth/shibd.logger

4.3 Shibboleth service provider

The main configuration of the Shibboleth Service Provider is done in /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"
    logger="syslog.logger" clockSkew="180">

    <!-- The OutOfProcess section contains properties affecting the shibd daemon. -->
    <OutOfProcess logger="/etc/shibboleth/shibd.logger">
        <!--
        <Extensions>
            <Library path="odbc-store.so" fatal="true"/>
        </Extensions>
        -->
    </OutOfProcess>
    
    <!-- The InProcess section conrains settings affecting web server modules/filters. -->
    <InProcess logger="/etc/shibboleth/native.logger">
        <ISAPI normalizeRequest="true">
            <!--
            Maps IIS Instance ID values to the host scheme/name/port/sslport. 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.
            The port and scheme can usually be omitted, so the HTTP request's port and
            scheme will be used.
            -->
            <Site id="1" name="sp.example.org"/>
        </ISAPI>
    </InProcess>

    <!-- Only one listener can be defined, to connect in process modules to shibd. -->
    <!-- Unix based systems --> <!-- <UnixListener address="shibd.sock"/> -->
    <!-- Windows systems --> <!-- <TCPListener address="127.0.0.1" port="1600" acl="127.0.0.1"/> -->
    <UnixListener address="shibd.sock" />
    
    <!-- This set of components stores sessions and other persistent data in daemon memory. -->
    <StorageService type="Memory" id="mem" cleanupInterval="900"/>
    <SessionCache type="StorageService" StorageService="mem" cacheTimeout="3600" inprocTimeout="900" cleanupInterval="900"/>
    <ReplayCache StorageService="mem"/>
    <ArtifactMap artifactTTL="180"/>

    <!-- This set of components stores sessions and other persistent data in an ODBC database. -->
    <!--
    <StorageService type="ODBC" id="db" cleanupInterval="900">
        <ConnectionString>
        DRIVER=drivername;SERVER=dbserver;UID=shibboleth;PWD=password;DATABASE=shibboleth;APP=Shibboleth
        </ConnectionString>
    </StorageService>
    <SessionCache type="StorageService" StorageService="db" cacheTimeout="3600" inprocTimeout="900" cleanupInterval="900"/>
    <ReplayCache StorageService="db"/>
    <ArtifactMap StorageService="db" artifactTTL="180"/>
    -->

    <!-- To customize behavior, map hostnames and path components to applicationId and other settings. -->
    <RequestMapper type="Native">
        <RequestMap applicationId="default">
            <!--
            The example 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.
    Resource requests are mapped by the RequestMapper to an applicationId that
    points into to this section.
    -->
    <ApplicationDefaults id="default" policyId="default"
        entityID="https://sp.example.org/shibboleth"
        homeURL="https://sp.example.org/"
        REMOTE_USER="eppn persistent-id targeted-id"
        signing="false" encryption="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 can be a relative path, a URL with no hostname (https:///path) or a full URL.
        The system can compute a relative value based on the virtual host. Using handlerSSL="true"
        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"
            handlerURL="/Shibboleth.sso" handlerSSL="true"
            exportLocation="http://localhost/Shibboleth.sso/GetAssertion"
            idpHistory="false" idpHistoryDays="7">
        
            <!-- For an http only (non SSL) service, set handlerSSL="false".
                 Assure that the URLs in the metadata (resource registry)
                 are set appropiate -->           
 
            <!--
            SessionInitiators handle session requests and relay them to a Discovery page,
            or to an IdP if possible. Automatic session setup will use the default or first
            element (or requireSessionWith can specify a specific id to use).
            -->

            <!-- Default example supporting the new-style of discovery service. -->
            <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>
            
            <!-- An example using an old-style WAYF, which means Shib 1 only unless an entityID is provided. -->
            <!--
            <SessionInitiator type="Chaining" Location="/WAYF" id="WAYF" relayState="cookie">
                <SessionInitiator type="SAML2" acsByIndex="false" acsIndex="1" template="bindingTemplate.html"/>
                <SessionInitiator type="Shib1" acsIndex="5"/>
                <SessionInitiator type="WAYF" acsIndex="5" URL="https://wayf.switch.ch/SWITCHaai/WAYF"/>
            </SessionInitiator>
            -->

            <!-- An example directs to a specific IdP's SSO service (favoring SAML 2 over Shib 1). -->
            <!--
            <SessionInitiator type="Chaining" Location="/Login" id="MyIdP"
                    relayState="cookie" entityID="https://idp.example.org/idp/shibboleth">
                <SessionInitiator type="SAML2" acsByIndex="false" acsIndex="1" template="bindingTemplate.html"
                    outgoingBindings="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" />
                <SessionInitiator type="Shib1" acsIndex="5"/>
            </SessionInitiator>
            -->

            
            <!--
            md:AssertionConsumerService locations handle specific SSO protocol bindings,
            such as SAML 2.0 POST or SAML 1.1 Artifact. The isDefault and index attributes
            are used when sessions are initiated to determine how to tell the IdP where and
            how to return the response.
            -->
            <md:AssertionConsumerService Location="/SAML2/POST" index="1"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
            <md:AssertionConsumerService Location="/SAML2/POST-SimpleSign" index="2"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign"/>
            <md:AssertionConsumerService Location="/SAML2/Artifact" index="3"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>
            <md:AssertionConsumerService Location="/SAML2/ECP" index="4"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS"/>
            <md:AssertionConsumerService Location="/SAML/POST" index="5"
                Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/>
            <md:AssertionConsumerService Location="/SAML/Artifact" index="6"
                Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/>

            <!-- LogoutInitiators enable SP-initiated local or global/single logout of sessions. -->
            <LogoutInitiator type="Chaining" Location="/Logout" relayState="cookie">
            <!--<LogoutInitiator type="SAML2" template="bindingTemplate.html"/>-->
                <LogoutInitiator type="Local"/>
            </LogoutInitiator>

            <!-- md:SingleLogoutService locations handle single logout (SLO) protocol messages. -->
            <md:SingleLogoutService Location="/SLO/SOAP"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
            <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
            <md:SingleLogoutService Location="/SLO/POST" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
            <md:SingleLogoutService Location="/SLO/Artifact" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>

            <!-- md:ManageNameIDService locations handle NameID management (NIM) protocol messages. -->
            <md:ManageNameIDService Location="/NIM/SOAP"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
            <md:ManageNameIDService Location="/NIM/Redirect" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
            <md:ManageNameIDService Location="/NIM/POST" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
            <md:ManageNameIDService Location="/NIM/Artifact" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>

            <!--
            md:ArtifactResolutionService locations resolve artifacts issued when using the
            SAML 2.0 HTTP-Artifact binding on outgoing messages, generally uses SOAP.
            -->
            <md:ArtifactResolutionService Location="/Artifact/SOAP" index="1"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>

            <!-- 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"/>

        </Sessions>

        <!--
        You should customize these pages! You can add attributes with values that can be plugged
        into your templates. You can remove the access attribute to cause the module to return a
        standard 403 Forbidden error code if authorization fails, and then customize that condition
        using your web server.
        -->
        <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"/>
        <!-- Uncomment and modify to tweak settings for specific IdPs or groups. -->
        <!-- <RelyingParty Name="SpecialFederation" keyName="SpecialKey"/> -->

        <!-- Chains together all your metadata sources. -->
        <MetadataProvider type="Chaining">
            <!-- Example of remotely supplied batch of signed metadata. -->
            <MetadataProvider type="XML" uri="http://metadata.aai.switch.ch/metadata.switchaai.xml"
                 backingFilePath="/etc/shibboleth/metadata.switchaai.xml" reloadInterval="3600">
              <MetadataFilter type="RequireValidUntil" maxValidityInterval="604800"/>
              <MetadataFilter type="Signature" verifyName="false">
                <TrustEngine type="StaticPKIX" verifyDepth="5">
                  <CredentialResolver type="File">
                    <Certificate format="PEM">
                      <Path>/etc/shibboleth/SWITCHaaiRootCA.crt.pem</Path>
                    </Certificate>
                  </CredentialResolver>
                </TrustEngine>
              </MetadataFilter>
            </MetadataProvider>

            <!-- Example of locally maintained metadata. -->
            <!--
            <MetadataProvider type="XML" file="partner-metadata.xml"/>
            -->
        </MetadataProvider>

        <!-- Chain the two built-in trust engines together. -->
        <TrustEngine type="Chaining">
            <TrustEngine type="ExplicitKey"/>
            <TrustEngine type="PKIX"/>
        </TrustEngine>

        <!-- Map to extract attributes from SAML assertions. -->
        <AttributeExtractor type="XML" path="/etc/shibboleth/attribute-map.xml"/>
        <!-- Attribute map fresh from resource registry -->
        <!--
        <AttributeExtractor type="XML" uri="https://rr.aai.switch.ch/gen_attribute-map.php"/>
        -->
        
        <!-- Use a SAML query if no attributes are supplied during SSO. -->
        <AttributeResolver type="Query"/>

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" path="/etc/shibboleth/attribute-policy.xml"/>
        <!-- Attribute policy fresh from resource registry -->
        <!--
        <AttributeExtractor type="XML" uri="https://rr.aai.switch.ch/gen_attribute-policy.php"/>
        -->

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

        <!-- Example of a second application (using a second vhost) that has a different entityID. -->
        <!-- <ApplicationOverride id="admin" entityID="https://admin.example.org/shibboleth"/> -->

    </ApplicationDefaults>
    
    <!-- Each policy defines a set of rules to use to secure messages. -->
    <SecurityPolicies>
        <!-- The predefined policy enforces replay/freshness and permits signing and client TLS. -->
        <Policy id="default" validate="false">
            <PolicyRule type="MessageFlow" checkReplay="true" expires="60"/>
            <PolicyRule type="ClientCertAuth" errorFatal="true"/>
            <PolicyRule type="XMLSigning" errorFatal="true"/>
            <PolicyRule type="SimpleSigning" errorFatal="true"/>
        </Policy>
    </SecurityPolicies>

</SPConfig>
Download the attribute map, where the attribute definition and its map to the HTTP-Header names are done: 
sudo wget -nc https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.3/sp/deployment/download/attribute-map.xml -P /etc/shibboleth/
Warning In case of an update, you should backup your /etc/shibboleth/attribute-map.xml first!
Note By default, Shibboleth 2.x uses environment variables instead of HTTP headers to improve security. If you need the HTTP Headers (i.e. by using mod_jk) you have to set the Apache directive ShibUseHeaders On within your protected application. For further information, refer to the Internet 2 Shibbolet SP 2 documentation.
Download the attribute filtering policy (aka. AAP): 
sudo wget -nc  https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.3/sp/deployment/download/attribute-policy.xml -P /etc/shibboleth/
Warning In case of an update, you should backup your /etc/shibboleth/attribute-policy.xml first!

4.4 Download federation specific file

Donwload the trust anchor of the metadata signature: 
sudo wget http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem -P /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 /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.

Define a redirect in the Apache virtual host section of the Service Provider, e.g. /etc/apache2/sites-enabled/sp.example.org: 
<VirtualHost sp.example.org:443>

...

  Redirect seeother /shibboleth https://sp.example.org/Shibboleth.sso/Metadata

</VirtualHost>

5. Run & Test

Test the configuration file: 
sudo /opt/shibboleth-sp2/sbin/shibd -t -c /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: 
sudo /etc/init.d/shibd start
Test configuration and restart Apache: 
sudo apache2ctl configtest
sudo apache2ctl restart
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 /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.

Simple Test Resource

For a real test that shows if the Service Provider retrieves any attributes from an Identity Provider, you first must protect a resource,
e.g. https://sp.example.org/secure/.
This can be accomplished by adding the following directives to the Apache site config,
e.g. /etc/apache2/sites-enabled/sp.example.org: 
<VirtualHost sp.example.org:443>
...

  <Location /secure>

    AuthType shibboleth
    ShibRequireSession On
    require valid-user
  </Location>

</VirtualHost>
Restart Apache: 
sudo apache2ctl restart
Note Further information about protecting resources with Shibboleth can be found at SWITCHaai - How to protect a resource with Shibboleth access rules web page.

After restarting Apache, try to access: https://sp.example.org/secure/, the authentication should be initiated and you should be redirected either to the WAYF or to an Identity Provider.
Upon successful authentication, you will probably encounter a 404 (File not found) error, because there might be no /secure.
Anyway, if you can access https://sp.example.org/Shibboleth.sso/Session to get information about the session like the issuer (IdP) and released attributes, this proofs the proper operation of the Service Provider.

If more testing is needed, e.g. to get the values of the released attributes, add a simple PHP script into the secure/ directory, like that index.php: 
<html><body><pre>
<?php print_r($_SERVER); ?>
</pre></body></html>
This PHP script has to be placed in a Shibboleth protected directory (e.g. /secure from above). If successfully authenticated and authorized, you should see some environment variables contain your user attributes.

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 /etc/shibboleth/native.logger or /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 /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 $